Xin playback

Cấp vé playback ngắn hạn: cho một tập, hoặc một batch tối đa 3 tập (tập người xem bắt đầu cộng tối đa hai tập prefetch). Backend của bạn gọi endpoint này mỗi khi người xem bắt đầu một tập và chuyển kết quả cho Player SDK trên thiết bị của người xem. Quy tắc về thời hạn, tái sử dụng và batch: Hành vi chuẩn của API.

POST /api/delivery/v1/playback

Scope: playback (Developers → Stream films in an app; xem Xác thực)

Mô tả

Ở mọi request, Wandura kiểm tra rằng tổ chức của bạn đang hoạt động và giấy phép streaming cho phim chứa tập đó đang hoạt động và nằm trong khung thời gian. Sau đó Wandura trả về một play token gắn với thiết bị của người xem. Các tập được cấp phép đều đã mã hoá và chỉ phát được qua Player SDK, nên bạn phải gửi các giá trị thiết bị union_info và drm_kek. Xem Playback.

Chỉ gọi endpoint này từ backend. Endpoint không gửi header CORS.

Tham số request

Tên	Vị trí	Kiểu	Bắt buộc	Mô tả
`Authorization`	header	string	Có	`Bearer <API key>` của một key có scope `playback`.
`Content-Type`	header	string	Nên có	`application/json`. Body phải là JSON.
`Wandura-Version`	header	string	Không	Tuỳ chọn. Một phiên bản API theo ngày (YYYY-MM-DD) dùng cho request này thay cho bản ghim vào API key của bạn. Giá trị lạ hoặc đã ngừng trả 400 với `error_code` `unsupported_version`.
`Wandura-Simulate`	header	string	Không	Tuỳ chọn, chỉ với tổ chức thử. Yêu cầu Wandura trả một lỗi giả lập để bạn thử cách app xử lý nó, ví dụ `rate_limited`, `service_unavailable` hay `not_entitled:outside_window`. Response giả lập có cùng status, body và header với response thật, cộng header `Wandura-Simulated` nêu tên kịch bản. Nó không cấp vé và không tính vào rate limit, trừ `partial_batch` (phần tử đầu là vé thật). Response giả lập có giới hạn riêng 300 lần mỗi phút mỗi tổ chức. Key của tổ chức production bỏ qua hoàn toàn header này. Giá trị lạ, hoặc kịch bản endpoint không hỗ trợ, bị bỏ qua và request chạy bình thường. Xem hướng dẫn Testing để biết danh sách kịch bản.
`episode_id`	body	string (UUID)	Một trong hai: `episode_id` hoặc `film_ref` + `episode_no`	`id` của tập lấy từ catalog. Được ưu tiên nếu bạn gửi kèm `film_ref`.
`film_ref`	body	string	Cùng `episode_no`, nếu không có `episode_id`	`id` hoặc `slug` của phim.
`episode_no`	body	integer	Cùng `film_ref`, nếu không có `episode_id`	Số tập, bắt đầu từ 1. Phải là số JSON, không phải string.
`union_info`	body	string	Có, với tập đã mã hoá	Device ID do Player SDK tạo ra trên thiết bị của người xem. Gửi cùng `drm_kek`. Bị từ chối với 400 `invalid_device_info` khi, sau khi bỏ khoảng trắng hai đầu, giá trị ngắn hơn 8 ký tự hoặc là một trong `(null)`, `null`, `nil`, `undefined`, `nan`, `<null>`, `none` (chữ hoa hay thường đều tính).
`drm_kek`	body	string	Có, với tập đã mã hoá	Device public key do Player SDK tạo ra. Gửi cùng `union_info`. Kiểm như `union_info`. Khoá riêng tương ứng không bao giờ rời thiết bị.
`intent`	body	string	Không	`play` khi người xem chạm vào tập, `prefetch` khi app tải tập trước khi người xem chạm. Request prefetch không tính là lượt phát. Thiếu trường này hoặc giá trị khác được ghi nhận là không xác định, không bao giờ bị từ chối, và vẫn tính là lượt phát.
`viewer_ref`	body	string	Không	Định danh phiên hoặc thiết bị opaque của riêng bạn, được lưu cùng vé để tra cứu khi hỗ trợ (tối đa 256 ký tự). Đừng đưa dữ liệu cá nhân vào. Khi bạn gửi trường này, xin lại cùng một tập với cùng `viewer_ref`, intent (`play` hay `prefetch`) và giá trị thiết bị trong lúc vé trước còn ít nhất 5 phút sẽ nhận lại đúng vé đó (cùng `expires_at`, không gia hạn) và không bị tính vào rate limit.
`episodes`	body	array	Không	Lô dạng A — tối đa 3 tập trong một lần gọi (thường là tập đang xem + 2 tập kế). Không dùng chung với `episode_id` / `film_ref` / `episode_no` ở cấp ngoài hay với `next`. Phần tử 0 lấy `intent` cấp ngoài; các phần tử sau mặc định là `prefetch` trừ khi tự khai.
`episodes[].episode_id`	body	string (UUID)	Không	Episode ID. Hoặc gửi `film_ref` + `episode_no`.
`episodes[].film_ref`	body	string	Không	`id` hoặc `slug` của phim, đi cùng `episode_no`.
`episodes[].episode_no`	body	integer	Không	Số tập (số nguyên từ 1), đi cùng `film_ref`.
`episodes[].intent`	body	string	Không	Intent của phần tử này.
`next`	body	integer	Không	Lô dạng B — cùng một tập neo (`episode_id`, hoặc `film_ref` + `episode_no`), cấp thêm vé cho N tập kế tiếp của cùng phim. Các tập kế được ghi là `prefetch`. Tập vượt quá cuối phim hoặc chưa publish là lỗi 404 `not_ready` của riêng phần tử đó. Gửi `next` (kể cả 0) là chuyển response sang dạng lô.

Ví dụ request

curl -s -X POST https://www.wandura.ai/api/delivery/v1/playback \
  -H "Authorization: Bearer $WANDURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "film_ref": "the-heiress-returns",
    "episode_no": 1,
    "union_info": "<device ID from the Player SDK>",
    "drm_kek": "<device public key from the Player SDK>",
    "intent": "play",
    "viewer_ref": "u_48213:dev_9a7c"
  }'

Response

200 OK

Trường	Kiểu	Mô tả
`vid`	string	Video ID để tải trong Player SDK. Đi cùng `play_auth_token`.
`play_auth_token`	string	Play token để đưa cho Player SDK. Giữ bí mật và không ghi log.
`manifest_url`	string	Link stream đã ký, thay cho `vid` + `play_auth_token`, chỉ có với nội dung Wandura giao cho tổ chức của bạn không mã hoá theo thoả thuận (khi đó `protection` là `signed-url-only`). Dùng được tới `expires_at`.
`expires_at`	string (ISO 8601, UTC)	Thời điểm vé hết hạn: 30 phút sau khi được cấp (15 phút với `manifest_url`).
`protection`	string	Mức bảo vệ của nội dung bạn nhận được. `private-encrypted` với các tập được cấp phép. Chỉ bán tập trả phí khi giá trị là `private-encrypted`.
`subtitles`	array	Phụ đề gắn với tập, theo thứ tự `lang`. Rỗng khi chưa có phụ đề nào.
`subtitles[].lang`	string	Mã ngôn ngữ, ví dụ `en`, `vi` hoặc `pt-BR`.
`subtitles[].url`	string	URL của file phụ đề. Không gắn với thời hạn của vé.
`subtitles[].format`	string	Luôn là `webvtt`.
`items`	array	Chỉ có ở lô — mỗi tập được hỏi một phần tử, theo thứ tự hỏi. Khi `status` là 200 phần tử còn có `episode_id`, `episode_no` và các trường vé như response một tập; ngược lại có `error`, `error_code`, `reason` (403, và 429 `prefetch_shed`, nếu có) và `retry_after` (503 và 429), không có dữ liệu tập.
`items[].request`	object	Lặp lại thứ đã hỏi cho phần tử này.
`items[].status`	integer	Status kiểu HTTP của riêng phần tử này.
`items[].subtitles[].lang`	string	Mã ngôn ngữ, ví dụ `en`, `vi` hoặc `pt-BR`.
`items[].subtitles[].url`	string	URL của file phụ đề. Không gắn với thời hạn của vé.
`items[].subtitles[].format`	string	Luôn là `webvtt`.
`items[].retry_after`	integer	Số giây cần chờ trước khi thử lại phần tử này (503 và 429).

Ví dụ response

{
  "vid": "v0d2f8c1a9e4b7",
  "play_auth_token": "eyJhbGciOi...placeholder...",
  "expires_at": "2026-10-01T12:30:00.000Z",
  "protection": "private-encrypted",
  "subtitles": [
    { "lang": "en", "url": "https://cdn.example.com/subtitles/heiress-ep1-en.vtt", "format": "webvtt" },
    { "lang": "vi", "url": "https://cdn.example.com/subtitles/heiress-ep1-vi.vtt", "format": "webvtt" }
  ]
}

Header của response

Header	Response	Mô tả
`Wandura-API-Status`	mọi response	Trạng thái API. Hiện là `beta`, ở mọi response, thành công hay lỗi.
`Wandura-Version`	mọi response	Phiên bản API theo ngày (YYYY-MM-DD) mà response này dùng: bản ghim vào API key của bạn, hoặc bản bạn gửi trong header request `Wandura-Version`. Key tạo trước khi có phiên bản ngày dùng `2026-10-02`.
`Wandura-Request-Id`	mọi response	Mã định danh mờ của request này (`req_` và 26 ký tự). Mọi response đều có, kể cả lỗi, và body lỗi lặp lại nó ở `request_id`. Hãy ghi log nó, và gửi kèm khi liên hệ Wandura về một request: nó tìm đúng request đó trong log của chúng tôi. Đừng phân tích chuỗi này.
`Cache-Control`	mọi response	Luôn là `no-store`. Đừng lưu các response này trong cache dùng chung.
`Deprecation`	200	Chỉ có khi endpoint này, hoặc phiên bản ngày đang phục vụ response, đã bị ngừng hỗ trợ (RFC 9745): `@<giây unix>` của ngày ngừng. Hãy ghi nó vào hệ giám sát.
`Sunset`	200	Chỉ có khi endpoint hay phiên bản ngày đã bị ngừng có ngày thôi chạy (RFC 8594), dạng ngày HTTP.
`Link`	200	Có kèm `Deprecation`: `<https://docs.wandura.ai/…>; rel="deprecation"` (và `rel="sunset"`) trỏ tới trang giải thích dùng gì thay thế.
`Retry-After`	429, 503	Số giây cần chờ trước khi thử lại. Có ở response 429 và các response 503 nên thử lại.
`X-RateLimit-Limit`	429	Số request (với playback là số vé) được phép trong một cửa sổ cho nhóm endpoint này và tổ chức của bạn.
`X-RateLimit-Window`	429	Độ dài cửa sổ tính bằng giây.

Lỗi

Status	`error_code`	Khi nào
400	không có	Body không phải JSON hợp lệ, hoặc không có `episode_id` cũng không có `film_ref` kèm `episode_no` dạng số.
400	`invalid_request`	Chỉ gửi một trong hai `union_info` và `drm_kek`, hoặc lô sai dạng (`episodes` rỗng hay dài hơn 3, một phần tử không chỉ tập nào, `episodes` dùng chung với trường tập cấp ngoài hay với `next`, `next` ngoài 0–2 hoặc không có tập neo).
400	`invalid_device_info`	Một giá trị thiết bị trông như rỗng hoặc quá ngắn. Mảng `fields` nêu tên giá trị đó.
400	`unsupported_version`	Header `Wandura-Version`, hoặc bản ghim của key, là bản lạ hay đã ngừng. Body có thêm `supported_versions` và `latest_version` (và `upgrade_to` khi bản ghim đã ngừng).
401	không có	Thiếu header `Authorization: Bearer`, hoặc key không tồn tại hay đã bị thu hồi.
403	không có	Key thiếu scope `playback`.
403	`not_entitled`	Tổ chức của bạn hiện không được phép stream phim này. `reason` là một trong `org_suspended`, `entitlement_not_found`, `entitlement_suspended`, `streaming_disabled`, `outside_window`.
404	`not_ready`	Phim hoặc tập không tồn tại, chưa publish, hoặc chưa sẵn sàng để stream.
409	`sdk_required`	Tập đã mã hoá và request không có giá trị thiết bị. Body còn kèm `protection`.
429	`rate_limited`	Đã chạm rate limit của playback, hoặc (khi `reason` là `prefetch_shed`) prefetch bị tạm dừng vì lưu lượng playback của bạn đã gần mức đó. Xem `Retry-After`.
502	không có	Không chuẩn bị được stream hoặc không ký được play token. Retry với backoff.
503	`not_ready`	Hiện chưa có phiên bản phát được của tập.
503	`service_unavailable`	Wandura chưa kiểm được API key kịp thời. Key không sai: thử lại sau số giây trong `Retry-After`, có backoff.
503	`service_unavailable`	Nhà cung cấp video chưa trả lời kịp (`The video provider did not answer in time — retry`). Tập phim không bị thiếu: thử lại sau số giây trong `Retry-After`, có backoff.
503	`service_unavailable`	Wandura chưa kiểm được giấy phép hoặc tập phim kịp thời (`Could not check the licence or episode right now — retry`). Điều này không nói gì về giấy phép hay tập phim: cứ tiếp tục bán, và thử lại sau số giây trong `Retry-After`, có backoff.

Ví dụ 403:

{
  "error": "outside_window",
  "error_code": "not_entitled",
  "reason": "outside_window"
}

Cách xử lý từng trường hợp: Lỗi.

Xin playback

Mô tả#

Tham số request#

Ví dụ request#

Response#

Ví dụ response#

Header của response#

Lỗi#