Bắt đầu nhanh

TL;DR — Phần A (khoảng 5 phút, chỉ cần server): tạo key, đọc cấu hình, liệt kê catalog. Phần B (cần app của bạn chạy trên điện thoại thật có Player SDK): lấy vé đầu tiên và phát một tập. Không test vé được chỉ bằng curl: các giá trị thiết bị của vé chỉ có trên thiết bị.

Mọi lệnh bên dưới dùng một biến môi trường là WANDURA_API_KEY. Phần B thêm UNION_INFO và DRM_KEK, sao chép từ app của bạn.

Trước khi bắt đầu#

• Một tài khoản thành viên có vai trò Admin hoặc Developer trong tổ chức của bạn trên partner.wandura.ai. Chưa có quyền truy cập? Xem Trước khi bắt đầu.
• Ít nhất một phim đã được cấp phép cho tổ chức của bạn, nếu không catalog sẽ rỗng.
• Chỉ cho Phần B: Player SDK đã được cài trong app, kèm giấy phép cho các app ID của bạn. Xem Player SDK.

Phần A — những lệnh gọi đầu tiên (chỉ server)#

Bước 1: Tạo key#

Cần: vai trò Admin hoặc Developer.

1. Đăng nhập partner.wandura.ai và mở Developers → Create a key.
2. Đặt label, ví dụ quickstart, và chọn Stream films in an app. Key nhận metadata:read và playback.
3. Chọn Create key và sao chép key ngay: key chỉ hiện một lần.

export WANDURA_API_KEY="wnd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Nếu lỗi: không thấy trang Developers nghĩa là vai trò của bạn không phải Admin hay Developer: hãy hỏi Admin của tổ chức. Tiếp theo: bước 2.

Bước 2: Đọc cấu hình#

Cần: key từ bước 1 (scope nào cũng được).

curl -s https://www.wandura.ai/api/delivery/v1/config \
  -H "Authorization: Bearer $WANDURA_API_KEY"

Kết quả mong đợi: 200 kèm các scope của key, các giới hạn của bạn và phiên bản API mà key được ghim (đã rút gọn):

{
  "api": { "status": "beta", "version": "2026-10-02", "pinned_version": "2026-10-02", "latest_version": "2026-10-02" },
  "key": { "scopes": ["metadata:read", "playback"] },
  "rate_limits": { "window_seconds": 60, "doors": { "playback": { "limit": 10800, "unit": "tickets" } } },
  "playback": { "grant_ttl_seconds": 1800, "batch": { "max_episodes": 3, "max_next": 2 } }
}

Nếu lỗi: 401 = biến môi trường rỗng hoặc key bị gõ sai (echo ${#WANDURA_API_KEY} phải in ra 41). 503 = thử lại sau Retry-After. Tiếp theo: bước 3.

Bước 3: Liệt kê catalog#

Cần: một key có metadata:read.

curl -s https://www.wandura.ai/api/delivery/v1/catalog \
  -H "Authorization: Bearer $WANDURA_API_KEY"

Kết quả mong đợi: 200 kèm films (theo thứ tự hiển thị) và episodes (đã rút gọn):

{
  "films": [
    { "id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10", "title": "The Heiress Returns", "slug": "the-heiress-returns", "display_order": 10, "free_until_episode": 1 }
  ],
  "episodes": [
    { "id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e", "film_id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10", "episode_no": 1, "status": "published", "stream_ready": true, "poster_url": null }
  ]
}

Chọn một tập có "stream_ready": true và ghi lại id của nó cho Phần B. Catalog lớn? Phân trang bằng limit; xem Đồng bộ catalog.

Nếu lỗi: 200 rỗng ("films": []) nghĩa là tổ chức của bạn chưa có giấy phép nào đang hiệu lực, không phải key hỏng: hãy hỏi Wandura trong kênh Discord của team bạn. 403 = key thiếu metadata:read. Tiếp theo: xây job đồng bộ catalog, hoặc chuyển sang Phần B.

Phần B — vé đầu tiên trên thiết bị thật#

Cần: app của bạn chạy trên một iPhone hoặc điện thoại Android thật, Player SDK đã khởi động và đã qua bước kiểm giấy phép, và playback key nằm trên backend của bạn. Simulator và emulator không tạo ra giá trị thiết bị dùng được.

Cảnh báo: Mọi vé Wandura cấp đều được ghi nhận, và vé có "intent": "play" được tính là một lượt xem phim. Hãy làm các bước này với thiết bị thật và một người xem test thật, không dùng giá trị bịa ra.

Bước 4: Đọc giá trị thiết bị trong app#

Trong app, sau khi Player SDK đã khởi động, đọc device ID và device public key (lệnh gọi chính xác nằm trong hướng dẫn Player SDK trên portal), rồi ghi log chúng một lần trong bản build debug. Trên shell của backend:

export UNION_INFO="<device ID logged by your debug build>"
export DRM_KEK="<device public key logged by your debug build>"

Nếu lỗi: giá trị kiểu (null) hoặc chuỗi rỗng nghĩa là SDK chưa khởi động hoặc kiểm giấy phép thất bại. Xem Player SDK.

Bước 5: Xin vé#

Từ backend, cho tập bạn đã chọn ở bước 3:

curl -s -X POST https://www.wandura.ai/api/delivery/v1/playback \
  -H "Authorization: Bearer $WANDURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "episode_id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e",
    "union_info": "'"$UNION_INFO"'",
    "drm_kek": "'"$DRM_KEK"'",
    "viewer_ref": "qa-viewer-1:device-1",
    "intent": "play"
  }'

Nếu UNION_INFO và DRM_KEK rỗng, Wandura trả 409 sdk_required và không cấp gì.

Kết quả mong đợi: 200:

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

Nếu lỗi: 400 invalid_device_info = một giá trị thiết bị trông như rỗng (fields cho biết giá trị nào). 403 not_entitled = phim chưa được cấp phép cho tổ chức này. 404 not_ready = sai episode_id, hoặc tập chưa sẵn sàng. Mọi mã lỗi: Lỗi.

Bước 6: Phát#

Trả vid, play_auth_token và subtitles về đúng thiết bị đó. Tại đó, đưa video ID và token cho Player SDK rồi bắt đầu phát; SDK tự tải stream đã mã hoá và khoá của nó. Player HLS thông thường không phát được các tập này: nó tải playlist rồi đứng hình.

Kết quả mong đợi: tập bắt đầu phát trong vài giây. Nếu lỗi: xem Player SDK · các vấn đề thường gặp. Vé hết hạn vào expires_at (30 phút); xin lại cho cùng tập, trên cùng thiết bị, với cùng viewer_ref sẽ nhận lại đúng vé đó nếu vé còn hơn 5 phút.

Bước tiếp theo#

• Lộ trình tích hợp: toàn bộ lộ trình tới go-live.
• Luồng playback và paywall: endpoint backend mà app của bạn gọi, kèm code.
• Bảo mật: đọc trước khi đưa bất kỳ key nào lên một server dùng chung.