Bắt đầu nhanh

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ề.

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.

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

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:

{
  "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.

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.

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.

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

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. Khi next_cursor khác null, vẫn còn trang tiếp theo. Xem Phân trang.

Để 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.

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.

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

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());

{
  "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.

Bước tiếp theo

• Xác thực: scope, thời hạn, xoay vòng và thu hồi key.
• Phân phối 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: 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: 120 request mỗi phút cho mỗi key ở gói Enterprise.