Cấp một vé playback ngắn hạn cho một tập. 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.
POST /api/delivery/v1/playbackScope: playback (tự tạo trên Developers → Stream films in an app; 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)
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. |
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. |
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. |
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ợ. Đừng đưa dữ liệu cá nhân vào. |
union_info và drm_kek bị từ chối với 400 invalid_device_info khi, sau khi bỏ khoảng trắng hai đầu, một 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).
Ví dụ request
curl -s -X POST https://www.wandura.ai/api/delivery/v1/playback \
-H "Authorization: Bearer $WANDURA_PLAYBACK_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. |
play_auth_token |
string | Play token để đưa cho Player SDK. Giữ bí mật và không ghi log. |
expires_at |
string (ISO 8601, UTC) | Thời điểm vé hết hạn: 30 phút sau khi được cấp. |
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. 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. |
Phụ đề được trả về theo thứ tự lang.
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" }
]
}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. |
| 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ị đó. |
| 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. 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. |
Ví dụ 403:
{
"error": "outside_window",
"error_code": "not_entitled",
"reason": "outside_window"
}Xem Lỗi để biết cách xử lý từng trường hợp.
Cập nhật 01/10/2026 · Lịch sử thay đổi (3)