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

<!-- Generated from openapi/hills-v1.json by scripts/api-reference.mjs. Edit the operation in hills-music (server/lib/ops), not this page. -->

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

<a id="test-a-ddex-message-or-batch"></a>

## 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

```bash
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`

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

<a id="deliver-a-ddex-batch-ern-432-or-382-recommended"></a>

## 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

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

```bash
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`

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

<a id="list-deliveries"></a>

## 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

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

### Phản hồi `200`

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

<a id="start-a-direct-upload-large-batches"></a>

## 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

```bash
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`

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

<a id="where-a-direct-upload-stands"></a>

## 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

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

### Phản hồi `200`

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

<a id="drop-a-direct-upload"></a>

## 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

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

### Phản hồi `200`

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

<a id="commit-a-direct-upload"></a>

## 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

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

### Phản hồi `202`

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

<a id="delivery-status"></a>

## 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

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

### Phản hồi `200`

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

Nguồn: https://developer.hillsmusic.com/vi/reference/ddex-deliveries/