Phân phối DDEX

Phân phối các lô DDEX ERN (khuyến nghị 4.3.2 hoặc 3.8.2) lên Production, kiểm thử trước (không tạo gì), tải lên trực tiếp cho lô lớn, và trạng thái của chúng.

Base URL https://api.hillsmusic.com/v1. Mọi request đều gửi một API key: Authorization: Bearer hm_live_….

Kiểm thử một message hoặc lô DDEX
Phân phối một lô DDEX (khuyến nghị ERN 4.3.2 hoặc 3.8.2)
Liệt kê các lần phân phối
Bắt đầu tải lên trực tiếp (lô lớn)
Tình trạng một bản tải lên trực tiếp
Hủy một bản tải lên trực tiếp
Commit một bản tải lên trực tiếp
Trạng thái phân phối

Kiểm thử một message hoặc lô DDEX

POST /v1/ddex/validate · Scope: ddex:validate hoặc ddex:write

Đường kiểm thử: một tệp .xml (Content-Type: application/xml) hoặc .zip, được kiểm tra như một lần phân phối (XML, các quy tắc của HILLS, tệp audio, ảnh bìa và video, UPC và ISRC so với danh mục). Không có gì được tạo ra: không bản phát hành, bản ghi âm, nghệ sĩ, mã hay lần phân phối nào. Lần kiểm thử được liệt kê trên trang DDEX trong dashboard (Test reports). Phản hồi gồm mọi bước kiểm tra theo giai đoạn (pass / warning / error / skipped), những gì HILLS sẽ tạo, và kết luận: would_import, would_import_with_warnings, would_be_flagged hoặc would_be_rejected. ddex:write cũng dùng được.

Parameter

Parameter	Vị trí	Kiểu	Bắt buộc	Mô tả
`member_id`	query	integer	Không	Nghệ sĩ/hãng đĩa mà lô này dành cho (tài khoản của bạn nếu bỏ trống).
`name`	query	string	Không	Tên tệp cho body thô (mặc định batch.zip, hoặc message.xml với XML).

Body của request

Lô: tệp zip bạn vẫn phân phối cho các nền tảng (XML ERN + các tài nguyên mà nó tham chiếu) dưới dạng body thô, một tệp .xml riêng lẻ, hoặc trường multipart file (với member_id là một trường). Content type: application/zip, application/xml, multipart/form-data.

Ví dụ request

curl -X POST "https://api.hillsmusic.com/v1/ddex/validate?member_id=41" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @batch.zip

Phản hồi `200`

{
  "data": {
    "ern_version": "4.3",
    "verdict": "would_be_rejected",
    "summary": {
      "messages": 1,
      "releases": 1,
      "pass": 41,
      "warnings": 1,
      "errors": 2,
      "skipped": 1
    },
    "checks": [
      {
        "stage": "release",
        "label": "Label",
        "status": "error",
        "message": "ReleaseLabelReference is required…",
        "field": "Release/ReleaseLabelReference"
      }
    ]
  }
}

Lỗi

Mã trạng thái	Khi nào
400	invalid: một parameter bị sai; field cho biết parameter nào.
401	unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403	insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
413	too_large: lớn hơn mức một lần kiểm thử nhận được; hãy phân phối bằng POST /ddex.
429	busy: quá nhiều lần kiểm thử cùng lúc; hãy thử lại sau ít phút. rate_limited: chờ số giây ghi trong Retry-After.

Phân phối một lô DDEX (khuyến nghị ERN 4.3.2 hoặc 3.8.2)

POST /v1/ddex · Scope: ddex:write

Gửi tệp zip bạn vẫn phân phối cho các nền tảng: một hoặc nhiều XML ERN NewReleaseMessage cùng audio, ảnh bìa và video mà chúng tham chiếu. Dưới dạng body thô (Content-Type: application/zip, tối đa 20 GB) hoặc trường multipart file (tối đa 512 MB). Mỗi bản phát hành trở thành một bản nháp trên member_id (danh mục của chính bạn nếu bỏ trống); một UPC đã có sẽ cập nhật bản nháp của nó; yêu cầu gỡ và cập nhật bản phát hành đã lên kệ sẽ chờ đội ngũ HILLS xử lý. Khuyến nghị ERN 4.3.2 (namespace http://ddex.net/xml/ern/432) hoặc 3.8.2 (http://ddex.net/xml/ern/382); 4.3, 4.2, 4.1, 3.8.1, 3.8 và 3.7 được chấp nhận và đọc theo cùng cách (báo cáo cảnh báo 4.2, 4.1 và 3.7 là phiên bản cũ); các phiên bản khác bị từ chối. Trả về 202 kèm id của lần phân phối — hãy poll GET /ddex/{id}.

Parameter

Parameter	Vị trí	Kiểu	Bắt buộc	Mô tả
`member_id`	query	integer	Không	Nghệ sĩ/hãng đĩa mà lô này dành cho (tài khoản của bạn nếu bỏ trống).
`name`	query	string	Không	Tên tệp cho body thô (mặc định batch.zip).

Body của request

Ví dụ request

curl -X POST "https://api.hillsmusic.com/v1/ddex?member_id=41" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @batch.zip

Phản hồi `202`

{
  "data": {
    "id": 311,
    "status": "queued",
    "environment": "production",
    "status_url": "/v1/ddex/311"
  }
}

Lỗi

Mã trạng thái	Khi nào
400	invalid: một parameter bị sai; field cho biết parameter nào.
401	unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403	insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
413	too_large: quá 20 GB (body thô) hoặc 512 MB (multipart).
429	rate_limited: chờ số giây ghi trong Retry-After.

Liệt kê các lần phân phối

GET /v1/ddex · Scope: ddex:write hoặc ddex:validate

100 lần phân phối DDEX gần nhất của bạn, mới nhất trước (không gồm các bản tải lên chưa commit).

Ví dụ request

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

Phản hồi `200`

{
  "data": [
    {
      "id": 311,
      "member_id": 41,
      "environment": "production",
      "batch_name": "batch-0001.zip",
      "status": "done",
      "error": null,
      "message_id": "MSG-2026-0001",
      "ern_version": "4.3",
      "message_count": 1,
      "release_count": 1,
      "track_count": 12,
      "created_count": 1,
      "updated_count": 0,
      "flagged_count": 0,
      "left_out_count": 0,
      "release_ids": [
        912
      ],
      "created_at": "2026-10-07T09:00:00Z",
      "started_at": "2026-10-07T09:00:02Z",
      "finished_at": "2026-10-07T09:01:10Z"
    }
  ]
}

Lỗi

Mã trạng thái	Khi nào
401	unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403	insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
429	rate_limited: chờ số giây ghi trong Retry-After.

Bắt đầu tải lên trực tiếp (lô lớn)

POST /v1/ddex/uploads · Scope: ddex:write

Khuyến nghị cho tệp zip lớn: tệp đi thẳng vào kho lưu trữ thay vì qua API. Gửi tên tệp và kích thước tính bằng byte (tối đa 20 GB). Với tệp đến 64 MB, bạn nhận một URL để PUT toàn bộ tệp; lớn hơn thế, bạn nhận kích thước mỗi phần và một URL cho mỗi phần: PUT từng đoạn part_size byte (đoạn cuối ngắn hơn) lên URL của nó, theo thứ tự bất kỳ và song song. URL có hiệu lực 6 giờ; GET /ddex/uploads/{id} cấp URL mới cho các phần còn thiếu. Sau đó gọi POST /ddex/uploads/{id}/commit. DELETE /ddex/uploads/{id} hủy một bản tải lên bạn sẽ không hoàn tất; bản tải lên chưa commit bị xóa sau 7 ngày.

Body của request

JSON.

Trường	Kiểu	Bắt buộc	Mô tả
`name`	string	Có	Tên tệp (.zip hoặc .xml).
`size`	integer	Có	Kích thước tệp tính bằng byte.
`member_id`	integer	Không	Nghệ sĩ/hãng đĩa mà lô này dành cho (tài khoản của bạn nếu bỏ trống).

Ví dụ request

curl -X POST "https://api.hillsmusic.com/v1/ddex/uploads" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"batch-0001.zip","size":1073741824,"member_id":41}'

Phản hồi `201`

{
  "data": {
    "id": 312,
    "status": "uploading",
    "environment": "production",
    "name": "batch-0001.zip",
    "size": 1073741824,
    "expires_in": 21600,
    "upload": {
      "method": "multipart",
      "url": null,
      "part_size": 16777216,
      "parts": [
        {
          "part_number": 1,
          "url": "https://…"
        }
      ]
    },
    "commit_url": "/v1/ddex/uploads/312/commit"
  }
}

Lỗi

Mã trạng thái	Khi nào
400	invalid: một parameter bị sai; field cho biết parameter nào.
401	unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403	insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
429	rate_limited: chờ số giây ghi trong Retry-After.

Tình trạng một bản tải lên trực tiếp

GET /v1/ddex/uploads/{id} · Scope: ddex:write

Với bản tải lên chưa commit: URL mới cho các phần còn thiếu (URL ban đầu hết hạn sau 6 giờ), received_parts và parts_total. Sau khi commit: id của lần phân phối và status_url.

Parameter

Parameter	Vị trí	Kiểu	Bắt buộc	Mô tả
`id`	path	integer	Có	Id của bản tải lên.

Ví dụ request

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

Phản hồi `200`

{
  "data": {
    "id": 312,
    "status": "uploading",
    "environment": "production",
    "name": "batch-0001.zip",
    "size": 1073741824,
    "expires_in": 21600,
    "upload": {
      "method": "multipart",
      "url": null,
      "part_size": 16777216,
      "parts": [
        {
          "part_number": 7,
          "url": "https://…"
        }
      ]
    },
    "commit_url": "/v1/ddex/uploads/312/commit",
    "received_parts": 63,
    "parts_total": 64
  }
}

Lỗi

Mã trạng thái	Khi nào
401	unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403	insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
404	not_found: không tồn tại, hoặc không thuộc về bạn.
429	rate_limited: chờ số giây ghi trong Retry-After.

Hủy một bản tải lên trực tiếp

DELETE /v1/ddex/uploads/{id} · Scope: ddex:write

Hủy một bản tải lên bạn sẽ không hoàn tất, cùng các phần đã gửi. 409 nếu đã commit.

Parameter

Parameter	Vị trí	Kiểu	Bắt buộc	Mô tả
`id`	path	integer	Có	Id của bản tải lên.

Ví dụ request

curl -X DELETE "https://api.hillsmusic.com/v1/ddex/uploads/312" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Phản hồi `200`

{
  "data": {
    "id": 312,
    "deleted": true
  }
}

Lỗi

Mã trạng thái	Khi nào
401	unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403	insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
404	not_found: không tồn tại, hoặc không thuộc về bạn.
409	already_committed: đã commit nên không thể hủy.
429	rate_limited: chờ số giây ghi trong Retry-After.

Commit một bản tải lên trực tiếp

POST /v1/ddex/uploads/{id}/commit · Scope: ddex:write

Kiểm tra mọi phần đã đến đủ và đúng kích thước, rồi đưa lô vào hàng đợi giống hệt POST /ddex. 409 upload_incomplete liệt kê các phần còn thiếu và sai kích thước (hãy tải chúng lên, rồi commit lại). Trả về 202 kèm id của lần phân phối; hãy poll GET /ddex/{id}.

Parameter

Parameter	Vị trí	Kiểu	Bắt buộc	Mô tả
`id`	path	integer	Có	Id của bản tải lên.

Ví dụ request

curl -X POST "https://api.hillsmusic.com/v1/ddex/uploads/312/commit" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Phản hồi `202`

{
  "data": {
    "id": 312,
    "status": "queued",
    "environment": "production",
    "status_url": "/v1/ddex/312"
  }
}

Lỗi

Mã trạng thái	Khi nào
401	unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403	insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
404	not_found: không tồn tại, hoặc không thuộc về bạn.
409	upload_incomplete: thiếu phần hoặc phần sai kích thước (liệt kê trong missing, wrong_size). already_committed: đã commit trước đó (status_url trỏ đến lần phân phối). commit_in_progress: một lần commit khác của bản tải lên này đang chạy.
429	rate_limited: chờ số giây ghi trong Retry-After.

Trạng thái phân phối

GET /v1/ddex/{id} · Scope: ddex:write hoặc ddex:validate

queued → parsing → validating → importing → done / partial / failed, với một mục cho mỗi bản phát hành (được tạo, được cập nhật, gắn cờ chờ đội ngũ HILLS, bị bỏ qua, test) và mọi lỗi kèm trường DDEX liên quan. GET /ddex liệt kê 100 lần gần nhất của bạn.

Parameter

Parameter	Vị trí	Kiểu	Bắt buộc	Mô tả
`id`	path	integer	Có	Id của lần phân phối (từ POST /ddex hoặc lần commit).

Ví dụ request

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

Phản hồi `200`

{
  "data": {
    "id": 311,
    "member_id": 41,
    "environment": "production",
    "status": "partial",
    "message_id": "MSG-2026-0001",
    "ern_version": "4.3",
    "created_count": 1,
    "left_out_count": 1,
    "items": [
      {
        "ref": "R0",
        "title": "Midnight Run",
        "upc": "0602600000017",
        "outcome": "created",
        "release_id": 912,
        "errors": []
      }
    ]
  }
}

Lỗi

Mã trạng thái	Khi nào
401	unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired.
403	insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan.
404	not_found: không tồn tại, hoặc không thuộc về bạn.
429	rate_limited: chờ số giây ghi trong Retry-After.

Phân phối DDEX

Kiểm thử một message hoặc lô DDEX

Parameter

Body của request

Ví dụ request

Phản hồi 200

Lỗi

Phân phối một lô DDEX (khuyến nghị ERN 4.3.2 hoặc 3.8.2)

Parameter

Body của request

Ví dụ request

Phản hồi 202

Lỗi

Liệt kê các lần phân phối

Ví dụ request

Phản hồi 200

Lỗi

Bắt đầu tải lên trực tiếp (lô lớn)

Body của request

Ví dụ request

Phản hồi 201

Lỗi

Tình trạng một bản tải lên trực tiếp

Parameter

Ví dụ request

Phản hồi 200

Lỗi

Hủy một bản tải lên trực tiếp

Parameter

Ví dụ request

Phản hồi 200

Lỗi

Commit một bản tải lên trực tiếp

Parameter

Ví dụ request

Phản hồi 202

Lỗi

Trạng thái phân phối

Parameter

Ví dụ request

Phản hồi 200

Lỗi

Sẵn sàng tích hợp?

Phản hồi `200`

Phản hồi `202`

Phản hồi `200`

Phản hồi `201`

Phản hồi `200`

Phản hồi `200`

Phản hồi `202`

Phản hồi `200`