Lịch sử thay đổi
Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.
- 05/10/2026 · +2 −0 dòng
Xem thay đổi
⋯ | `GET` | `/api/delivery/v1/creatives/{id}` | `creatives:export` | [Lấy một creative](creatives-get.md) | | `POST` | `/api/delivery/v1/playback` | `playback` | [Xin playback](playback.md) | + | `GET` | `/api/delivery/v1/playlists` | `metadata:read` | [Liệt kê playlist video để đồng bộ metadata](playlists-list.md) | + | `GET` | `/api/delivery/v1/playlists/{code}` | `metadata:read` | [Lấy metadata một playlist video](playlists-get.md) | | `GET` | `/api/delivery/v1/series` | `metadata:read` | [Liệt kê bộ phim để đồng bộ metadata](series-list.md) | | `GET` | `/api/delivery/v1/series/{code}` | `metadata:read` | [Lấy metadata một bộ phim](series-get.md) | ⋯
- 04/10/2026 · +2 −0 dòng
Xem thay đổi
⋯ | `GET` | `/api/delivery/v1/creatives/{id}` | `creatives:export` | [Lấy một creative](creatives-get.md) | | `POST` | `/api/delivery/v1/playback` | `playback` | [Xin playback](playback.md) | + | `GET` | `/api/delivery/v1/series` | `metadata:read` | [Liệt kê bộ phim để đồng bộ metadata](series-list.md) | + | `GET` | `/api/delivery/v1/series/{code}` | `metadata:read` | [Lấy metadata một bộ phim](series-get.md) | | `GET` | `/api/delivery/v1/videos` | `videos:read` | [Liệt kê video mở](videos-list.md) | | `GET` | `/api/delivery/v1/videos/{id}` | `videos:read` | [Một video mở kèm link phát mới](videos-get.md) | ⋯
- 02/10/2026 · +25 −102 dòng
Xem thay đổi
# Tài liệu tham chiếu API - Wandura Delivery API cho phép backend của bạn đọc các phim bạn được cấp phép, xin playback cho từng tập một, và đồng bộ các ad creative đã duyệt. Phần này mô tả từng endpoint. Về luồng tích hợp, hãy bắt đầu với [Bắt đầu nhanh](../quickstart.md), [Xác thực](../authentication.md) và [Playback](../concepts/playback.md). + Phần tham chiếu mô tả từng endpoint của Wandura Delivery API: tham số, trường, ví dụ, header và lỗi, sinh ra từ bản mô tả OpenAPI. Các quy tắc chung cho mọi endpoint — xác thực, phân trang, thời hạn vé, độ mới, retry, rate limit, phiên bản — nằm ở [Hành vi chuẩn của API](behaviour.md). - ## Base URL + ## Base URL {#base-url} ``` ⋯ ``` - Luôn gọi `www.wandura.ai`. Tên miền trần `wandura.ai` trả mọi request bằng một redirect `308` sang `www`, và một số HTTP client làm rơi body hoặc header của `POST` khi đi theo redirect. + Luôn dùng `www.wandura.ai`. Tên miền trần trả `308` sang `www`, và một số HTTP client làm rơi body hoặc header của `POST` khi đi theo redirect. - ## Endpoint + ## Endpoint {#endpoints} | Method | Path | Scope | Trang | |---|---|---|---| | `GET` | `/api/delivery/v1/catalog` | `metadata:read` | [Lấy catalog được cấp phép](catalog.md) | - | `GET` | `/api/delivery/v1/config` | `any` | Lấy cấu hình | + | `GET` | `/api/delivery/v1/config` | `any` | [Lấy cấu hình](config.md) | | `GET` | `/api/delivery/v1/creatives` | `creatives:export` | [Liệt kê creative](creatives-list.md) | | `GET` | `/api/delivery/v1/creatives/{id}` | `creatives:export` | [Lấy một creative](creatives-get.md) | | `POST` | `/api/delivery/v1/playback` | `playback` | [Xin playback](playback.md) | - | `GET` | `/api/delivery/v1/videos` | `videos:read` | [Liệt kê video mở](../open-video.md) | - | `GET` | `/api/delivery/v1/videos/{id}` | `videos:read` | Một video mở kèm link phát mới | - - `GET /api/delivery/v1/config` — [Lấy cấu hình](config.md), gọi được bằng mọi key hợp lệ. + | `GET` | `/api/delivery/v1/videos` | `videos:read` | [Liệt kê video mở](videos-list.md) | + | `GET` | `/api/delivery/v1/videos/{id}` | `videos:read` | [Một video mở kèm link phát mới](videos-get.md) | - Mọi đường dẫn khác dưới `/api/delivery/v1/`, với bất kỳ method nào, trả `404` kèm body JSON phẳng và `error_code` `not_found`. Nếu gặp nó ở một đường dẫn bạn tưởng là đúng, hãy soát lỗi gõ trong đường dẫn. + Mọi đường dẫn khác dưới `/api/delivery/v1/` trả `404` `not_found`; một đường dẫn có thật nhưng sai method trả `405`. Hợp đồng cho máy đọc: bản mô tả OpenAPI 3 của mọi endpoint ở trên được đăng tại [https://docs.wandura.ai/developers/openapi/delivery-v1.json](https://docs.wandura.ai/developers/openapi/delivery-v1.json). Dùng nó để sinh client hoặc kiểm tra tích hợp của bạn. Trong `/v1` nó chỉ thay đổi theo kiểu thêm vào. - ## Chỉ server-to-server - - Gọi các endpoint này từ backend, không bao giờ từ trình duyệt hay app di động. Chúng không gửi header CORS, và API key không bao giờ được nằm trong client. - - ## Xác thực - - Gửi API key dưới dạng bearer token ở mọi request: - - ``` - Authorization: Bearer <your API key> - ``` - - Mỗi key thuộc về một tổ chức và mang một hoặc nhiều scope. Key bị thiếu, không tồn tại hoặc đã thu hồi nhận `401`. Key hợp lệ nhưng thiếu scope của endpoint nhận `403`. + ## Chỉ server-to-server {#server-to-server-only} - | Scope | Cấp quyền | Cách lấy | - |---|---|---| - | `metadata:read` | [Lấy catalog được cấp phép](catalog.md) | Tự tạo trên partner portal | - | `creatives:export` | [Liệt kê creative](creatives-list.md), [Lấy một creative](creatives-get.md) | Tự tạo trên partner portal | - | `webhooks:manage` | Chưa có endpoint nào dùng | Tự tạo trên partner portal | - | `playback` | [Xin playback](playback.md) | Tự tạo trên partner portal (**Stream films in an app**) | + Gọi các endpoint này từ backend, không bao giờ từ trình duyệt hay app: chúng không gửi header CORS, và key nằm trong client thì có thể bị trích ra. Xem [Bảo mật](../concepts/security.md). - Thành viên tổ chức có vai trò **Admin** hoặc **Developer** tạo, xoay vòng và thu hồi key trên trang **Developers** của partner portal. Key đầy đủ chỉ hiện một lần, lúc tạo. Kể cả key có scope `playback`: nếu key bị lộ, bất kỳ ai cũng stream được phim bạn được cấp phép, nên hãy thu hồi ngay. Xem [Xác thực](../authentication.md). + ## Request và response {#requests-and-responses} - ## Phiên bản + - Body là JSON. Gửi `Content-Type: application/json` với `POST`. + - ID của phim, tập, creative và video là chuỗi UUID. + - Thời gian là chuỗi ISO 8601 theo UTC (`expires_at`), trừ feed creative, nơi dùng giây Unix epoch. + - Mọi response đều mang `Wandura-Version` và `Wandura-API-Status: beta`. + - Bỏ qua các trường, giá trị và mã lỗi bạn không nhận ra: xem [Phiên bản và tiến hoá API](../concepts/versioning.md#tolerant-reader). - Phiên bản API nằm trong path (`/v1`). Trong cùng một phiên bản, Wandura có thể thêm trường response mới và mã lỗi mới mà không báo trước. Hãy bỏ qua các trường bạn không nhận ra, và luôn có nhánh mặc định cho mã lỗi lạ. Thế nào là phá vỡ tương thích, và phiên bản cũ được hỗ trợ bao lâu: [Phiên bản và ngừng hỗ trợ](../concepts/versioning.md). + ## Các quy tắc chung nằm ở đâu {#shared-rules} - Bản ghi creative còn mang trường `schema_version`, hiện là `1`. Trường được bổ sung thêm không làm thay đổi giá trị này. + | Chủ đề | Trang | + |---|---| + | Key, scope | [Xác thực](../authentication.md) | + | Phân trang, vé, độ mới, retry, rate limit, phiên bản | [Hành vi chuẩn của API](behaviour.md) | + | Mọi lỗi, theo từng endpoint | [Lỗi](../concepts/errors.md) | + | Rate limit khi tải cao | [Rate limit](../concepts/rate-limits.md) | + | Phiên bản theo ngày, ngừng hỗ trợ | [Phiên bản và tiến hoá API](../concepts/versioning.md) | ### Beta {#beta} - API đang ở bản **beta**. Mọi response từ `/v1` đều mang header `Wandura-API-Status: beta`. Trong giai đoạn beta, Wandura vẫn có thể đổi cách hoạt động bên trong `/v1`; các thay đổi được ghi ở **Nhật ký thay đổi** (link cuối mọi trang). Thấy chỗ sai hoặc thiếu? Bấm **Gửi góp ý** ở đầu mọi trang docs. - - ## Request và response - - - Body của request và response là JSON. Gửi `Content-Type: application/json` với `POST`. - - ID của phim, tập và creative là chuỗi UUID. - - Playback trả `expires_at` dạng timestamp ISO 8601 theo UTC. Endpoint creatives trả timestamp dạng giây Unix epoch. - - Endpoint creatives gửi `Cache-Control: no-store`. Đừng cache response của chúng trong cache dùng chung. - - ## Pagination - - Chỉ [Liệt kê creative](creatives-list.md) có phân trang. Endpoint này dùng `cursor` opaque và trả `next_cursor` cho đến khi hết bản ghi. [Lấy catalog được cấp phép](catalog.md) trả toàn bộ catalog trong một response. - - ## Lỗi - - API dùng hai định dạng lỗi. Endpoint catalog và playback trả về một object phẳng: - - ```json - { - "error": "Episode not found or not ready to stream", - "error_code": "not_ready" - } - ``` - - | Trường | Kiểu | Mô tả | - |---|---|---| - | `error` | string | Thông điệp cho người đọc. Đừng parse. Một ngoại lệ: `403` của catalog không có `error_code`, và `error` đúng bằng `org_suspended` khi tổ chức bạn bị tạm ngưng. Xem [Liệt kê catalog có giấy phép](catalog.md#errors). | - | `error_code` | string | Mã máy đọc được. Rẽ nhánh theo trường này. Một số lỗi không có trường này, ví dụ `401`. | - | `reason` | string | Có mặt cùng `not_entitled`. Lý do chi tiết, dùng cho log và hỗ trợ. | - - Endpoint creatives bọc mọi response, dù thành công hay lỗi, trong một envelope có `code` dạng số: - - ```json - { - "code": 4011, - "message": "Invalid or revoked API key", - "server_time": 1790679032 - } - ``` - - | Trường | Kiểu | Mô tả | - |---|---|---| - | `code` | integer | `0` khi thành công. Mã lỗi bốn chữ số trong trường hợp khác. | - | `message` | string | `"ok"` khi thành công, thông điệp cho người đọc trong trường hợp khác. | - | `data` | object | Chỉ có khi thành công. | - | `server_time` | integer | Giờ server tính bằng giây Unix epoch. | - - Trang của từng endpoint liệt kê lỗi của endpoint đó. Về hướng dẫn retry và danh sách đầy đủ, xem [Lỗi](../concepts/errors.md). - - ## Rate limit - - Mỗi tổ chức có một ngưỡng chống lạm dụng cho từng nhóm endpoint, đếm trong một cửa sổ cố định 60 giây: 10.800 request playback (khoảng 180 vé mỗi giây), 3.000 request catalog và 3.000 request creatives, mỗi nhóm một bộ đếm riêng. Chạm ngưỡng thường có nghĩa là có vòng lặp chạy mất kiểm soát. Wandura nâng được bất kỳ ngưỡng nào riêng cho tổ chức của bạn khi bạn yêu cầu, có hiệu lực trong khoảng một phút. Các header giới hạn dưới đây chỉ xuất hiện trên response `429`. - - Khi bạn chạm ngưỡng, mọi endpoint, kể cả endpoint creatives, đều trả `429` với body phẳng: - - ```json - { - "error": "Too many playback requests for this account. This is an abuse ceiling, not a quota — if a normal integration reaches it, contact us and it will be raised.", - "error_code": "rate_limited" - } - ``` - - | Header | Mô tả | - |---|---| - | `Retry-After` | Số giây cho đến khi cửa sổ hiện tại reset. | - | `X-RateLimit-Limit` | Số request được phép trong mỗi cửa sổ cho nhóm endpoint này. | - | `X-RateLimit-Window` | Độ dài cửa sổ tính bằng giây. | - - Chờ hết `Retry-After` rồi mới retry. Xem [Rate limit](../concepts/rate-limits.md#limits). + API đang ở bản **beta**. Trong giai đoạn beta, Wandura vẫn có thể đổi hành vi bên trong `/v1`, theo [quy tắc beta](../concepts/versioning.md#beta); mọi thay đổi đều có trong nhật ký thay đổi.
- 02/10/2026 · +1 −0 dòng
Xem thay đổi
⋯ | `POST` | `/api/delivery/v1/playback` | `playback` | [Xin playback](playback.md) | | `GET` | `/api/delivery/v1/videos` | `videos:read` | [Liệt kê video mở](../open-video.md) | + | `GET` | `/api/delivery/v1/videos/{id}` | `videos:read` | Một video mở kèm link phát mới | `GET /api/delivery/v1/config` — [Lấy cấu hình](config.md), gọi được bằng mọi key hợp lệ. ⋯
- 02/10/2026 · +2 −1 dòng
Xem thay đổi
⋯ |---|---|---|---| | `GET` | `/api/delivery/v1/catalog` | `metadata:read` | [Lấy catalog được cấp phép](catalog.md) | + | `GET` | `/api/delivery/v1/config` | `any` | Lấy cấu hình | | `GET` | `/api/delivery/v1/creatives` | `creatives:export` | [Liệt kê creative](creatives-list.md) | | `GET` | `/api/delivery/v1/creatives/{id}` | `creatives:export` | [Lấy một creative](creatives-get.md) | ⋯ | `GET` | `/api/delivery/v1/videos` | `videos:read` | [Liệt kê video mở](../open-video.md) | - **Đang triển khai:** `GET /api/delivery/v1/config` — [Lấy cấu hình](config.md), gọi được bằng mọi key hợp lệ. + `GET /api/delivery/v1/config` — [Lấy cấu hình](config.md), gọi được bằng mọi key hợp lệ. Mọi đường dẫn khác dưới `/api/delivery/v1/`, với bất kỳ method nào, trả `404` kèm body JSON phẳng và `error_code` `not_found`. Nếu gặp nó ở một đường dẫn bạn tưởng là đúng, hãy soát lỗi gõ trong đường dẫn. ⋯
- 02/10/2026 · +4 −1 dòng
Xem thay đổi
⋯ |---|---|---|---| | `GET` | `/api/delivery/v1/catalog` | `metadata:read` | [Lấy catalog được cấp phép](catalog.md) | - | `POST` | `/api/delivery/v1/playback` | `playback` | [Xin playback](playback.md) | | `GET` | `/api/delivery/v1/creatives` | `creatives:export` | [Liệt kê creative](creatives-list.md) | | `GET` | `/api/delivery/v1/creatives/{id}` | `creatives:export` | [Lấy một creative](creatives-get.md) | + | `POST` | `/api/delivery/v1/playback` | `playback` | [Xin playback](playback.md) | + | `GET` | `/api/delivery/v1/videos` | `videos:read` | [Liệt kê video mở](../open-video.md) | **Đang triển khai:** `GET /api/delivery/v1/config` — [Lấy cấu hình](config.md), gọi được bằng mọi key hợp lệ. ⋯ Mọi đường dẫn khác dưới `/api/delivery/v1/`, với bất kỳ method nào, trả `404` kèm body JSON phẳng và `error_code` `not_found`. Nếu gặp nó ở một đường dẫn bạn tưởng là đúng, hãy soát lỗi gõ trong đường dẫn. + Hợp đồng cho máy đọc: bản mô tả OpenAPI 3 của mọi endpoint ở trên được đăng tại [https://docs.wandura.ai/developers/openapi/delivery-v1.json](https://docs.wandura.ai/developers/openapi/delivery-v1.json). Dùng nó để sinh client hoặc kiểm tra tích hợp của bạn. Trong `/v1` nó chỉ thay đổi theo kiểu thêm vào. + ## Chỉ server-to-server ⋯
- 02/10/2026 · +2 −0 dòng
Xem thay đổi
⋯ | `GET` | `/api/delivery/v1/creatives/{id}` | `creatives:export` | [Lấy một creative](creatives-get.md) | + **Đang triển khai:** `GET /api/delivery/v1/config` — [Lấy cấu hình](config.md), gọi được bằng mọi key hợp lệ. + Mọi đường dẫn khác dưới `/api/delivery/v1/`, với bất kỳ method nào, trả `404` kèm body JSON phẳng và `error_code` `not_found`. Nếu gặp nó ở một đường dẫn bạn tưởng là đúng, hãy soát lỗi gõ trong đường dẫn. ⋯
- 01/10/2026 · +3 −3 dòng
Xem thay đổi
⋯ | `creatives:export` | [Liệt kê creative](creatives-list.md), [Lấy một creative](creatives-get.md) | Tự tạo trên partner portal | | `webhooks:manage` | Chưa có endpoint nào dùng | Tự tạo trên partner portal | - | `playback` | [Xin playback](playback.md) | Chỉ Wandura cấp | + | `playback` | [Xin playback](playback.md) | Tự tạo trên partner portal (**Stream films in an app**) | - Thành viên tổ chức có vai trò **Admin** hoặc **Developer** tạo, xoay vòng và thu hồi key trên trang **Developers** của partner portal. Key đầy đủ chỉ hiện một lần, lúc tạo. Key có scope `playback` do Wandura quản lý và không xoay vòng được từ portal. Xem [Xác thực](../authentication.md). + Thành viên tổ chức có vai trò **Admin** hoặc **Developer** tạo, xoay vòng và thu hồi key trên trang **Developers** của partner portal. Key đầy đủ chỉ hiện một lần, lúc tạo. Kể cả key có scope `playback`: nếu key bị lộ, bất kỳ ai cũng stream được phim bạn được cấp phép, nên hãy thu hồi ngay. Xem [Xác thực](../authentication.md). ## Phiên bản ⋯ ## Rate limit - Mỗi tổ chức có một ngưỡng chống lạm dụng cho từng nhóm endpoint, đếm trong một cửa sổ cố định 60 giây: 30.000 request playback, và 3.000 request dùng chung cho endpoint catalog và creatives. Ngưỡng này cao hơn rất nhiều so với lưu lượng bình thường, nên chạm ngưỡng thường có nghĩa là có vòng lặp chạy mất kiểm soát. Wandura nâng được ngưỡng khi bạn yêu cầu. Các header giới hạn dưới đây chỉ xuất hiện trên response `429`. + Mỗi tổ chức có một ngưỡng chống lạm dụng cho từng nhóm endpoint, đếm trong một cửa sổ cố định 60 giây: 10.800 request playback (khoảng 180 vé mỗi giây), 3.000 request catalog và 3.000 request creatives, mỗi nhóm một bộ đếm riêng. Chạm ngưỡng thường có nghĩa là có vòng lặp chạy mất kiểm soát. Wandura nâng được bất kỳ ngưỡng nào riêng cho tổ chức của bạn khi bạn yêu cầu, có hiệu lực trong khoảng một phút. Các header giới hạn dưới đây chỉ xuất hiện trên response `429`. Khi bạn chạm ngưỡng, mọi endpoint, kể cả endpoint creatives, đều trả `429` với body phẳng: ⋯
- 01/10/2026 · +5 −3 dòng
Xem thay đổi
⋯ | `GET` | `/api/delivery/v1/creatives/{id}` | `creatives:export` | [Lấy một creative](creatives-get.md) | + Mọi đường dẫn khác dưới `/api/delivery/v1/`, với bất kỳ method nào, trả `404` kèm body JSON phẳng và `error_code` `not_found`. Nếu gặp nó ở một đường dẫn bạn tưởng là đúng, hãy soát lỗi gõ trong đường dẫn. + ## Chỉ server-to-server ⋯ | Trường | Kiểu | Mô tả | |---|---|---| - | `error` | string | Thông điệp cho người đọc. Đừng parse. | + | `error` | string | Thông điệp cho người đọc. Đừng parse. Một ngoại lệ: `403` của catalog không có `error_code`, và `error` đúng bằng `org_suspended` khi tổ chức bạn bị tạm ngưng. Xem [Liệt kê catalog có giấy phép](catalog.md#errors). | | `error_code` | string | Mã máy đọc được. Rẽ nhánh theo trường này. Một số lỗi không có trường này, ví dụ `401`. | | `reason` | string | Có mặt cùng `not_entitled`. Lý do chi tiết, dùng cho log và hỗ trợ. | ⋯ ## Rate limit - Mỗi tổ chức có một ngưỡng chống lạm dụng cho từng nhóm endpoint, đếm trong một cửa sổ thời gian cố định. Ngưỡng này cao hơn rất nhiều so với lưu lượng bình thường, nên chạm ngưỡng thường có nghĩa là có vòng lặp chạy mất kiểm soát. Endpoint catalog và creatives dùng chung một bộ đếm; playback có bộ đếm riêng. + Mỗi tổ chức có một ngưỡng chống lạm dụng cho từng nhóm endpoint, đếm trong một cửa sổ cố định 60 giây: 30.000 request playback, và 3.000 request dùng chung cho endpoint catalog và creatives. Ngưỡng này cao hơn rất nhiều so với lưu lượng bình thường, nên chạm ngưỡng thường có nghĩa là có vòng lặp chạy mất kiểm soát. Wandura nâng được ngưỡng khi bạn yêu cầu. Các header giới hạn dưới đây chỉ xuất hiện trên response `429`. Khi bạn chạm ngưỡng, mọi endpoint, kể cả endpoint creatives, đều trả `429` với body phẳng: ⋯ | `X-RateLimit-Window` | Độ dài cửa sổ tính bằng giây. | - Chờ hết `Retry-After` rồi mới retry. Xem [Rate limit](../concepts/rate-limits.md). + Chờ hết `Retry-After` rồi mới retry. Xem [Rate limit](../concepts/rate-limits.md#limits).
- 01/10/2026 · +1 −1 dòng
Xem thay đổi
⋯ ## Phiên bản - Phiên bản API nằm trong path (`/v1`). Trong cùng một phiên bản, Wandura có thể thêm trường response mới và mã lỗi mới mà không báo trước. Hãy bỏ qua các trường bạn không nhận ra, và luôn có nhánh mặc định cho mã lỗi lạ. + Phiên bản API nằm trong path (`/v1`). Trong cùng một phiên bản, Wandura có thể thêm trường response mới và mã lỗi mới mà không báo trước. Hãy bỏ qua các trường bạn không nhận ra, và luôn có nhánh mặc định cho mã lỗi lạ. Thế nào là phá vỡ tương thích, và phiên bản cũ được hỗ trợ bao lâu: [Phiên bản và ngừng hỗ trợ](../concepts/versioning.md). Bản ghi creative còn mang trường `schema_version`, hiện là `1`. Trường được bổ sung thêm không làm thay đổi giá trị này. ⋯
- 01/10/2026 · +4 −0 dòng
Xem thay đổi
⋯ Bản ghi creative còn mang trường `schema_version`, hiện là `1`. Trường được bổ sung thêm không làm thay đổi giá trị này. + ### Beta {#beta} + + API đang ở bản **beta**. Mọi response từ `/v1` đều mang header `Wandura-API-Status: beta`. Trong giai đoạn beta, Wandura vẫn có thể đổi cách hoạt động bên trong `/v1`; các thay đổi được ghi ở **Nhật ký thay đổi** (link cuối mọi trang). Thấy chỗ sai hoặc thiếu? Bấm **Gửi góp ý** ở đầu mọi trang docs. + ## Request và response ⋯
- 29/09/2026 · Tạo trang