# Bắt đầu nhanh

> Tạo API key trong ứng dụng web HILLS, kiểm tra bằng /me, rồi liệt kê bản phát hành và đọc doanh thu của bạn. Chỉ mất khoảng năm phút.

Hướng dẫn này đưa bạn từ lúc chưa có key đến những dữ liệu thật đầu tiên. Bạn cần một tài khoản khách hàng dùng gói Enterprise hoặc Custom, và một terminal có `curl` hoặc Node 18 trở lên.

## 1. Tạo API key

1. Đăng nhập ứng dụng web HILLS và mở **Developers** ở thanh bên (`/dashboard/developers`).
2. Chọn **New API key**.
3. Đặt cho key một cái tên cho biết nó chạy ở đâu, ví dụ `ERP sync`.
4. Chọn scope. Mặc định gồm `members:read`, `catalog:read`, `earnings:read`, `payouts:read` và `links:read`. Chỉ thêm `ddex:write`, `ddex:validate` hoặc các scope webhook khi bạn thực sự cần.
5. Chọn thời điểm hết hạn, hoặc để key không bao giờ hết hạn.
6. Sao chép key từ hộp thoại **Copy your API key now**. Key chỉ hiển thị một lần. Sau đó, danh sách chỉ hiện tiền tố của key.

Bạn thấy **Developers** nếu bạn là chủ tài khoản, hoặc nếu vai trò của bạn trong nhóm có quyền API keys. Nếu nút bị mờ, gói của bạn không bao gồm API: hãy hỏi người phụ trách của bạn tại HILLS Music.

Hãy giữ key trên server của bạn. Đặt key trong biến môi trường, không bao giờ đặt trong trang web hay ứng dụng mà người khác tải về.

```bash
export HILLS_API_KEY="hm_live_…"
```

## 2. Kiểm tra key

`GET /me` trả về tài khoản sở hữu key, tên key, các scope và thời hạn của key. Endpoint này không cần scope cụ thể nào.

```bash
curl "https://api.hillsmusic.com/v1/me" \
  -H "Authorization: Bearer $HILLS_API_KEY"
```

```js
const res = await fetch("https://api.hillsmusic.com/v1/me", {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
console.log(res.status, await res.json());
```

Một key hợp lệ trả về `200`:

```json
{
  "partner": { "id": 12, "name": "Afterdark Music Group", "email": "ops@example.com" },
  "environment": "production",
  "key": {
    "id": 3,
    "name": "ERP sync",
    "prefix": "hm_live_ab12cd34",
    "environment": "production",
    "scopes": ["catalog:read", "earnings:read"],
    "expires_at": null,
    "created_at": "2026-10-01T09:00:00Z"
  }
}
```

`environment` luôn là `production`, vì chỉ có một loại key. Nếu bạn nhận `401` hoặc `403`, trường `code` trong phản hồi cho biết lý do. Xem [Lỗi](https://developer.hillsmusic.com/vi/guides/errors/).

`GET /ping` là một cách kiểm tra khác. Endpoint này còn trả về gói của bạn và số request bạn còn lại trong phút này. Xem [Tài khoản](https://developer.hillsmusic.com/vi/reference/account/).

## 3. Liệt kê bản phát hành

`GET /releases` cần `catalog:read`. Endpoint trả về các bản phát hành của nghệ sĩ và hãng đĩa của bạn, mới nhất trước, 50 bản mỗi trang.

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

```js
const res = await fetch("https://api.hillsmusic.com/v1/releases?limit=10", {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
const { data, next_cursor } = await res.json();
for (const r of data) console.log(r.id, r.title, r.release_status, r.delivery_state);
```

Mỗi bản phát hành có `release_status` (đang ở bước nào của kiểm duyệt) và `delivery_state` (đang ở đâu trên các nền tảng). Các giá trị có tại [Trạng thái](https://developer.hillsmusic.com/vi/reference/statuses/). Khi `next_cursor` khác null, vẫn còn trang tiếp theo. Xem [Phân trang](https://developer.hillsmusic.com/vi/guides/pagination/).

Để thu hẹp danh sách, thêm `status`, `member_id`, `upc` hoặc `q`. Để lấy một bản phát hành cùng các track và trạng thái trên từng nền tảng, gọi `GET /releases/{id}`. Xem [Bản phát hành](https://developer.hillsmusic.com/vi/reference/releases/).

## 4. Đọc doanh thu

`GET /earnings` cần `earnings:read`. Endpoint cộng doanh thu từ các sao kê nền tảng đã được ghi nhận, tính bằng USD.

```bash
curl "https://api.hillsmusic.com/v1/earnings?by=store&months=6" \
  -H "Authorization: Bearer $HILLS_API_KEY"
```

```js
const url = new URL("https://api.hillsmusic.com/v1/earnings");
url.searchParams.set("by", "store"); // month (default), release or store
url.searchParams.set("months", "6"); // 1–60, default 12
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
console.log(await res.json());
```

```json
{
  "by": "store",
  "months": 6,
  "currency": "USD",
  "data": [
    { "key": "Spotify", "label": "Spotify", "amount_usd": 1520.42, "member_share_usd": 1064.29, "units": 412003 }
  ]
}
```

`amount_usd` là tổng của bạn. `member_share_usd` là phần mà các tỷ lệ chia doanh thu (split) của bạn dành cho nghệ sĩ và hãng đĩa. Xem [Doanh thu](https://developer.hillsmusic.com/vi/reference/earnings/).

## Bước tiếp theo

- [Xác thực](https://developer.hillsmusic.com/vi/guides/authentication/): scope, thời hạn, xoay vòng và thu hồi key.
- [Phân phối DDEX](https://developer.hillsmusic.com/vi/guides/ddex/): bản phát hành vào HILLS dưới dạng các lô DDEX ERN. API không tạo hay sửa từng bản phát hành riêng lẻ.
- [Webhook](https://developer.hillsmusic.com/vi/guides/webhooks/): nhận thông báo khi một bản phát hành được duyệt, lên kệ hoặc khi một sao kê được công bố.
- [Rate limit](https://developer.hillsmusic.com/vi/guides/rate-limits/): 120 request mỗi phút cho mỗi key ở gói Enterprise.

Nguồn: https://developer.hillsmusic.com/vi/guides/quickstart/