# Wandura Delivery API

Wandura Delivery API cho phép backend của bạn stream các phim ngắn (short drama) mà tổ chức của bạn đã được Wandura cấp phép. Server của bạn đọc catalog được cấp phép, xin Wandura một vé playback ngắn hạn mỗi khi người xem bắt đầu một tập, rồi chuyển vé đó cho player trên thiết bị của người xem. Nếu tổ chức của bạn cũng dựng ad creative trên Wandura, cùng API này cung cấp cho hệ thống marketing của bạn một feed các creative đã được duyệt.

## API cung cấp gì

| Tính năng | Endpoint | Bạn nhận được |
|---|---|---|
| Catalog được cấp phép | `GET /api/delivery/v1/catalog` | Mọi phim và tập bạn được phép stream ngay lúc này, kèm thứ tự hiển thị, quy tắc tập miễn phí và cờ sẵn sàng cho từng tập. Chỉ có metadata, không bao giờ có URL video. |
| Vé playback | `POST /api/delivery/v1/playback` | Vé cho một tập, có hiệu lực 30 phút, kèm phụ đề của tập. |
| Feed creative | `GET /api/delivery/v1/creatives` và `GET /api/delivery/v1/creatives/{id}` | Một bản ghi dữ liệu cho mỗi ad creative đã duyệt của tổ chức bạn, để đồng bộ vào hệ thống marketing. |

## Base URL

```
https://www.wandura.ai
```

Dùng `www.wandura.ai`, không dùng tên miền trần `wandura.ai`. Tên miền trần redirect mọi request sang `www`, và một số HTTP client làm rơi body hoặc header của `POST` khi đi theo redirect.

## Các phần ghép với nhau thế nào

API này là server-to-server. API key nằm trên backend của bạn; thiết bị của người xem chỉ nhận vé playback cho tập sắp phát.

1. **Catalog.** Backend của bạn gọi `GET /catalog` và dựng danh sách phim từ response. Đừng giữ thêm một danh sách phim riêng: hai danh sách sẽ lệch nhau, và kết quả là có phim hiện ra nhưng không phát được.
2. **Vé playback.** Khi người xem chạm vào một tập, player trên thiết bị tạo ra hai giá trị thiết bị. Backend của bạn gửi hai giá trị này, cùng với tập, tới `POST /playback`. Wandura kiểm tra giấy phép của bạn cho phim đó ngay tại thời điểm ấy và trả về một vé.
3. **Player của bạn.** Thiết bị chuyển vé cho Player SDK, SDK sẽ tải stream đã mã hoá cùng khoá giải mã rồi phát.

Một lượt phát diễn ra như sau:

```mermaid
sequenceDiagram
    participant Device as Thiết bị người xem (Player SDK)
    participant Backend as Backend của bạn
    participant API as Wandura Delivery API
    participant Stream as Mạng streaming của Wandura
    Device->>Device: Người xem chạm vào một tập
    Device->>Backend: Tập + ID thiết bị + public key thiết bị
    Backend->>API: POST /api/delivery/v1/playback (Bearer API key)
    API->>API: Kiểm tra scope của key và giấy phép phim này
    API-->>Backend: vid, play_auth_token, expires_at, protection, subtitles
    Backend-->>Device: vid, play_auth_token, subtitles
    Device->>Stream: Player SDK tải stream đã mã hoá và khoá giải mã
    Stream-->>Device: Video phát
```

Khoá giải mã video được gắn với thiết bị của người xem. Khoá này không bao giờ đi qua backend của bạn và không xuất hiện trong response của API.

## Feed creative

Nếu tổ chức của bạn dựng ad creative với Wandura (ví dụ trên partner.wandura.ai), các creative đã duyệt sẽ xuất hiện trong feed creative. Mỗi bản ghi mô tả creative: phim, các tập và cảnh được dùng, định dạng, thời lượng, hook, formula và ngày hết quyền sử dụng. Feed không bao giờ chứa URL media. Xem [Creative](https://docs.wandura.ai/vi/developers/concepts/creatives).

## Bước tiếp theo

- [Bắt đầu nhanh](https://docs.wandura.ai/vi/developers/quickstart): thực hiện những lệnh gọi đầu tiên trong vài phút.
- [Xác thực](https://docs.wandura.ai/vi/developers/authentication): API key và scope.
- [Catalog](https://docs.wandura.ai/vi/developers/concepts/catalog), [Playback](https://docs.wandura.ai/vi/developers/concepts/playback) và [Creative](https://docs.wandura.ai/vi/developers/concepts/creatives): cách từng phần hoạt động.
- [Lỗi](https://docs.wandura.ai/vi/developers/concepts/errors) và [Rate limit](https://docs.wandura.ai/vi/developers/concepts/rate-limits): những gì có thể sai và cách xử lý.
- [Tài liệu tham chiếu API](https://docs.wandura.ai/vi/developers/reference/overview): mọi endpoint, tham số và trường.