# Tài liệu tham chiếu API

Phần tham chiếu mô tả từng endpoint của Wandura Delivery API: tham số, trường, ví dụ, header và lỗi, sinh ra từ bản mô tả OpenAPI. Các quy tắc chung cho mọi endpoint — xác thực, phân trang, thời hạn vé, độ mới, retry, rate limit, phiên bản — nằm ở [Hành vi chuẩn của API](https://docs.wandura.ai/vi/developers/reference/behaviour).

## Base URL
```
https://www.wandura.ai
```

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

## Endpoint
| Method | Path | Scope | Trang |
|---|---|---|---|
| `GET` | `/api/delivery/v1/catalog` | `metadata:read` | [Lấy catalog được cấp phép](https://docs.wandura.ai/vi/developers/reference/catalog) |
| `GET` | `/api/delivery/v1/config` | `any` | [Lấy cấu hình](https://docs.wandura.ai/vi/developers/reference/config) |
| `GET` | `/api/delivery/v1/creatives` | `creatives:export` | [Liệt kê creative](https://docs.wandura.ai/vi/developers/reference/creatives-list) |
| `GET` | `/api/delivery/v1/creatives/{id}` | `creatives:export` | [Lấy một creative](https://docs.wandura.ai/vi/developers/reference/creatives-get) |
| `POST` | `/api/delivery/v1/playback` | `playback` | [Xin playback](https://docs.wandura.ai/vi/developers/reference/playback) |
| `GET` | `/api/delivery/v1/playlists` | `metadata:read` | [Liệt kê playlist video để đồng bộ metadata](https://docs.wandura.ai/vi/developers/reference/playlists-list) |
| `GET` | `/api/delivery/v1/playlists/{code}` | `metadata:read` | [Lấy metadata một playlist video](https://docs.wandura.ai/vi/developers/reference/playlists-get) |
| `GET` | `/api/delivery/v1/series` | `metadata:read` | [Liệt kê bộ phim để đồng bộ metadata](https://docs.wandura.ai/vi/developers/reference/series-list) |
| `GET` | `/api/delivery/v1/series/{code}` | `metadata:read` | [Lấy metadata một bộ phim](https://docs.wandura.ai/vi/developers/reference/series-get) |
| `GET` | `/api/delivery/v1/videos` | `videos:read` | [Liệt kê video mở](https://docs.wandura.ai/vi/developers/reference/videos-list) |
| `GET` | `/api/delivery/v1/videos/{id}` | `videos:read` | [Một video mở kèm link phát mới](https://docs.wandura.ai/vi/developers/reference/videos-get) |

Mọi đường dẫn khác dưới `/api/delivery/v1/` trả `404` `not_found`; một đường dẫn có thật nhưng sai method trả `405`.

Hợp đồng cho máy đọc: bản mô tả OpenAPI 3 của mọi endpoint ở trên được đăng tại [https://docs.wandura.ai/developers/openapi/delivery-v1.json](https://docs.wandura.ai/developers/openapi/delivery-v1.json). Dùng nó để sinh client hoặc kiểm tra tích hợp của bạn. Trong `/v1` nó chỉ thay đổi theo kiểu thêm vào.

## Chỉ server-to-server
Gọi các endpoint này từ backend, không bao giờ từ trình duyệt hay app: chúng không gửi header CORS, và key nằm trong client thì có thể bị trích ra. Xem [Bảo mật](https://docs.wandura.ai/vi/developers/concepts/security).

## Request và response
- Body là JSON. Gửi `Content-Type: application/json` với `POST`.
- ID của phim, tập, creative và video là chuỗi UUID.
- Thời gian là chuỗi ISO 8601 theo UTC (`expires_at`), trừ feed creative, nơi dùng giây Unix epoch.
- Mọi response đều mang `Wandura-Version` và `Wandura-API-Status: beta`.
- Bỏ qua các trường, giá trị và mã lỗi bạn không nhận ra: xem [Phiên bản và tiến hoá API](https://docs.wandura.ai/vi/developers/concepts/versioning#tolerant-reader).

## Các quy tắc chung nằm ở đâu
| Chủ đề | Trang |
|---|---|
| Key, scope | [Xác thực](https://docs.wandura.ai/vi/developers/authentication) |
| Phân trang, vé, độ mới, retry, rate limit, phiên bản | [Hành vi chuẩn của API](https://docs.wandura.ai/vi/developers/reference/behaviour) |
| Mọi lỗi, theo từng endpoint | [Lỗi](https://docs.wandura.ai/vi/developers/concepts/errors) |
| Rate limit khi tải cao | [Rate limit](https://docs.wandura.ai/vi/developers/concepts/rate-limits) |
| Phiên bản theo ngày, ngừng hỗ trợ | [Phiên bản và tiến hoá API](https://docs.wandura.ai/vi/developers/concepts/versioning) |

### Beta
API đang ở bản **beta**. Trong giai đoạn beta, Wandura vẫn có thể đổi hành vi bên trong `/v1`, theo [quy tắc beta](https://docs.wandura.ai/vi/developers/concepts/versioning#beta); mọi thay đổi đều có trong nhật ký thay đổi.