# 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](https://partner.wandura.ai). Chưa có quyền truy cập? Xem [Trước khi bắt đầu](https://docs.wandura.ai/vi/developers/before-you-start#get-onboarded).
- Í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](https://docs.wandura.ai/vi/developers/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.

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

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

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

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

```json
{
  "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](https://docs.wandura.ai/vi/developers/guides/catalog-sync).

**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](https://docs.wandura.ai/vi/developers/guides/catalog-sync), 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:

```bash
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](https://docs.wandura.ai/vi/developers/player-sdk#common-problems).

### Bước 5: Xin vé
Từ backend, cho tập bạn đã chọn ở bước 3:

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

```json
{
  "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](https://docs.wandura.ai/vi/developers/concepts/errors#playback-errors).

### 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](https://docs.wandura.ai/vi/developers/player-sdk#common-problems). 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](https://docs.wandura.ai/vi/developers/integration-guide): toàn bộ lộ trình tới go-live.
- [Luồng playback và paywall](https://docs.wandura.ai/vi/developers/guides/playback-flow): endpoint backend mà app của bạn gọi, kèm code.
- [Bảo mật](https://docs.wandura.ai/vi/developers/concepts/security): đọc trước khi đưa bất kỳ key nào lên một server dùng chung.