# Gửi request

> Base URL, định dạng JSON của request và phản hồi, các header phản hồi, phiên bản và ngừng hỗ trợ, và những gì cần gửi bộ phận hỗ trợ khi có sự cố.

HILLS API là JSON qua HTTPS. Trang này trình bày những điểm chung của mọi request và phản hồi.

## Base URL

```
https://api.hillsmusic.com/v1
```

Chỉ có một base URL, dùng cho cả kiểm thử lẫn phân phối. Các cổng white-label cũng phản hồi trên tên miền riêng của chúng.

Base cũ, `https://app.hillsmusic.com/api/v1`, vẫn nhận cùng đường dẫn, key và trả về cùng phản hồi cho đến ngày **30/04/2027**. Sau ngày đó, base cũ ngừng phản hồi. Phản hồi từ base cũ mang header `Deprecation` và `Sunset`. Hãy chuyển sang `api.hillsmusic.com/v1` ngay bây giờ: chỉ base thay đổi. Xem [mục nhật ký thay đổi](https://developer.hillsmusic.com/vi/changelog/#2026-10-11-api-and-mcp-hosts).

## Xác thực

Mọi request đều gửi key của bạn:

```
Authorization: Bearer hm_live_…
```

Xem [Xác thực](https://developer.hillsmusic.com/vi/guides/authentication/). Chỉ gọi API từ server của bạn. API không gửi header CORS, nên trình duyệt không gọi được, và một key nằm trong trang web là một key đã bị lộ.

## Đọc dữ liệu

Thao tác đọc là các request `GET` với query parameter:

```bash
curl "https://api.hillsmusic.com/v1/releases?status=approved&limit=20" \
  -H "Authorization: Bearer $HILLS_API_KEY"
```

```js
const url = new URL("https://api.hillsmusic.com/v1/releases");
url.searchParams.set("status", "approved");
url.searchParams.set("limit", "20");
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
const { data } = await res.json();
```

Danh sách trả về `{ "data": [ … ] }`, đôi khi kèm các trường phân trang. Xem [Phân trang](https://developer.hillsmusic.com/vi/guides/pagination/). Một đối tượng đơn lẻ trả về `{ "data": { … } }`. Một số phản hồi có trường cấp cao nhất riêng, như `GET /me` và `GET /earnings`. Mỗi trang tham chiếu đều cho thấy cấu trúc chính xác.

## Gửi dữ liệu

Request `POST` và `PATCH` gửi body JSON với `Content-Type: application/json`:

```bash
curl -X POST "https://api.hillsmusic.com/v1/members/invite" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"luna@example.com","fname":"Luna","kind":"artist"}'
```

```js
const res = await fetch("https://api.hillsmusic.com/v1/members/invite", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HILLS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "luna@example.com", fname: "Luna", kind: "artist" }),
});
console.log(res.status, await res.json()); // 201 on success
```

Body không phải JSON hợp lệ sẽ được đọc như body rỗng. Khi đó phản hồi là `400 invalid`, với `field` nêu trường bắt buộc đầu tiên.

Phân phối DDEX là ngoại lệ: chúng gửi một tệp zip hoặc XML, không phải JSON. Xem [Phân phối DDEX](https://developer.hillsmusic.com/vi/guides/ddex/).

## Bạn có thể làm gì

API đọc thành viên, danh mục, doanh thu, thanh toán và smart link của bạn. API ghi dữ liệu ở ba chỗ: mời nghệ sĩ và hãng đĩa, phân phối các lô DDEX, và quản lý endpoint webhook.

API không hỗ trợ tạo hay sửa một bản phát hành theo từng trường. Hãy phân phối bản phát hành dưới dạng DDEX ERN (`POST /ddex`, khuyến nghị ERN 4.3.2 hoặc 3.8.2), hoặc dùng ứng dụng web.

## Định dạng

- **Thời gian** theo ISO 8601, múi giờ UTC, ví dụ `2026-10-13T09:00:00Z`.
- **Ngày** như `release_date` có dạng `YYYY-MM-DD`.
- **Tiền** tính bằng USD. `GET /earnings` dùng số thập phân (`amount_usd`). `GET /payouts` dùng số cent nguyên (`earned_cents`, `available_cents`).
- **ID** là số nguyên. ID sự kiện webhook là UUID.
- **URL ảnh bìa** (`cover_url`) có chữ ký và hết hạn khoảng 24 giờ sau khi phản hồi. Hãy lấy lại bản phát hành để có URL mới, và đừng lưu URL này.

## Header phản hồi

| Header | Khi nào | Ý nghĩa |
| --- | --- | --- |
| `X-RateLimit-Limit` | Mọi phản hồi | Số request mỗi phút key này được phép gửi. |
| `X-RateLimit-Remaining` | Mọi phản hồi | Số request còn lại trong phút này. |
| `Retry-After` | `429` | Số giây cần chờ. Xem [Rate limit](https://developer.hillsmusic.com/vi/guides/rate-limits/). |
| `X-HILLS-Environment` | Mọi phản hồi | Luôn là `production`. Được giữ lại cho các tích hợp có đọc header này. |
| `Deprecation`, `Sunset`, `Link` | Khi phản hồi dùng thứ sắp bị bỏ | Thời điểm bị đánh dấu ngừng hỗ trợ, thời điểm bị gỡ bỏ, và mục nhật ký thay đổi liên quan. |

<a id="versioning"></a>

## Phiên bản

Phiên bản nằm trong đường dẫn: `/v1`. Hãy viết client sao cho bỏ qua các trường nó không biết, để trường mới không làm hỏng client.

Khi cần bỏ một thứ gì đó trong v1, việc này được thông báo trong [nhật ký thay đổi](https://developer.hillsmusic.com/vi/changelog/) kèm ngày ngừng hỗ trợ. Cho đến ngày đó, các phản hồi có dùng đến nó mang header `Deprecation` (RFC 9745) và `Sunset` (RFC 8594), cùng một `Link` với `rel="deprecation"` trỏ đến mục nhật ký thay đổi. Ví dụ, trường `status` cũ trên bản phát hành sẽ bị gỡ vào ngày 30/04/2027. Hãy đọc `release_status` và `delivery_state` thay thế.

Hãy ghi log các header `Deprecation` trong client. Nhờ đó bạn biết về một thay đổi trước khi nó làm hỏng bất cứ thứ gì.

## Lỗi

Lỗi trả về một mã trạng thái và `{ "error": "…", "code": "…" }`. Hãy rẽ nhánh theo `code`, không theo nội dung văn bản. Xem [Lỗi](https://developer.hillsmusic.com/vi/guides/errors/).

## Khi cần hỗ trợ

Phản hồi không mang request ID. Khi liên hệ HILLS Music về một request, hãy gửi:

- method và đường dẫn, ví dụ `GET /v1/releases/812`;
- thời điểm, theo UTC;
- mã trạng thái và `code` bạn nhận được;
- tiền tố của key (`hm_live_ab12cd34`), không bao giờ gửi key đầy đủ.

Nhật ký request của key trên trang **Developers** hiển thị cùng các thông tin này trong 7 ngày gần nhất.

Nguồn: https://developer.hillsmusic.com/vi/guides/making-requests/