Lịch sử: Lấy cấu hình

Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.

02/10/2026 · +2 −1 dòng

Xem thay đổi

⋯
  | `Wandura-API-Status` | mọi response | Trạng thái API. Hiện là `beta`, ở mọi response, thành công hay lỗi. |
  | `Wandura-Version` | mọi response | Phiên bản API theo ngày (YYYY-MM-DD) mà response này dùng: bản ghim vào API key của bạn, hoặc bản bạn gửi trong header request `Wandura-Version`. Key tạo trước khi có phiên bản ngày dùng `2026-10-02`. |
+ | `Wandura-Request-Id` | mọi response | Mã định danh mờ của request này (`req_` và 26 ký tự). Mọi response đều có, kể cả lỗi, và body lỗi lặp lại nó ở `request_id`. Hãy ghi log nó, và gửi kèm khi liên hệ Wandura về một request: nó tìm đúng request đó trong log của chúng tôi. Đừng phân tích chuỗi này. |
  | `Deprecation` | 200 | Chỉ có khi endpoint này, hoặc phiên bản ngày đang phục vụ response, đã bị ngừng hỗ trợ (RFC 9745): `@<giây unix>` của ngày ngừng. Hãy ghi nó vào hệ giám sát. |
  | `Sunset` | 200 | Chỉ có khi endpoint hay phiên bản ngày đã bị ngừng có ngày thôi chạy (RFC 8594), dạng ngày HTTP. |
  | `Link` | 200 | Có kèm `Deprecation`: `<https://docs.wandura.ai/…>; rel="deprecation"` (và `rel="sunset"`) trỏ tới trang giải thích dùng gì thay thế. |
- | `Cache-Control` | 200 | Luôn là `no-store`. Đừng lưu các response này trong cache dùng chung. |
+ | `Cache-Control` | mọi response | Luôn là `no-store`. Đừng lưu các response này trong cache dùng chung. |
  | `Retry-After` | 429, 503 | Số giây cần chờ trước khi thử lại. Có ở response 429 và các response 503 nên thử lại. |
  | `X-RateLimit-Limit` | 429 | Số request (với playback là số vé) được phép trong một cửa sổ cho nhóm endpoint này và tổ chức của bạn. |
⋯

02/10/2026 · +57 −32 dòng

Xem thay đổi

  # Lấy cấu hình
  
- Trả về cấu hình áp cho API key đang gọi và tổ chức của nó: rate limit, tên miền phát, giới hạn lô, ngôn ngữ phụ đề, phiên bản API và các thông báo ngừng hỗ trợ. Đọc nó khi backend khởi động, hoặc vài giờ một lần, thay vì viết cứng các giá trị này. Xem [API tiến hoá](../concepts/api-evolution.md#config).
+ Trả về cấu hình áp dụng cho key đang gọi và tổ chức của nó: rate limit, cài đặt playback và thời hạn vé, giới hạn batch, ngôn ngữ phụ đề, phiên bản API và các thông báo ngừng hỗ trợ. Hãy đọc nó khi backend khởi động, hoặc vài giờ một lần, thay vì viết cứng các giá trị này. Xem [Phiên bản và tiến hoá API](../concepts/versioning.md#config).
  
  ```
⋯
  ```
  
- **Scope:** không cần — mọi API key hợp lệ.
+ **Scope:** mọi API key hợp lệ
  
- ## Tham số request
+ ## Tham số request {#request-parameters}
  
- | Tên | Ở | Kiểu | Bắt buộc | Mô tả |
+ | Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
  |---|---|---|---|---|
- | `Authorization` | header | string | Có | `Bearer <API key>`. |
- | `Wandura-Version` | header | string | Không | Một phiên bản ngày (`YYYY-MM-DD`) dùng cho request này thay cho bản ghim của key. Xem [Phiên bản theo ngày](../concepts/api-evolution.md#dated-versions). |
+ | `Authorization` | header | string | Có | `Bearer <API key>` của một key có scope `any`. |
+ | `Wandura-Version` | header | string | Không | Tuỳ chọn. Một phiên bản API theo ngày (YYYY-MM-DD) dùng cho request này thay cho bản ghim vào API key của bạn. Giá trị lạ hoặc đã ngừng trả 400 với `error_code` `unsupported_version`. |
+ | `Wandura-Simulate` | header | string | Không | Tuỳ chọn, chỉ với tổ chức thử. Yêu cầu Wandura trả một lỗi giả lập để bạn thử cách app xử lý nó, ví dụ `rate_limited`, `service_unavailable` hay `not_entitled:outside_window`. Response giả lập có cùng status, body và header với response thật, cộng header `Wandura-Simulated` nêu tên kịch bản. Nó không cấp vé và không tính vào rate limit, trừ `partial_batch` (phần tử đầu là vé thật). Response giả lập có giới hạn riêng 300 lần mỗi phút mỗi tổ chức. Key của tổ chức production bỏ qua hoàn toàn header này. Giá trị lạ, hoặc kịch bản endpoint không hỗ trợ, bị bỏ qua và request chạy bình thường. Xem hướng dẫn Testing để biết danh sách kịch bản. |
  
- ## Ví dụ request
+ ## Ví dụ request {#request-example}
  
  ```bash
⋯
  ```
  
- ## Response
+ ## Response {#response}
  
- `200 OK`. Trường mới có thể được thêm bất cứ lúc nào: bỏ qua những trường bạn không nhận ra.
+ `200 OK`. Trường mới có thể được thêm bất cứ lúc nào: hãy bỏ qua những trường bạn không nhận ra.
  
  | Trường | Kiểu | Mô tả |
⋯
  | `api.status` | string | `beta` khi API còn beta. |
  | `api.path_version` | string | Phiên bản lớn trong path, `v1`. |
- | `api.version` | string | Phiên bản ngày mà chính response này dùng (cũng có ở header response `Wandura-Version`). |
+ | `api.version` | string | Phiên bản ngày mà response này dùng. |
  | `api.pinned_version` | string | Phiên bản ngày ghim vào key đang gọi. |
  | `api.latest_version` | string | Phiên bản ngày mới nhất. |
- | `api.version_header` | string | `Wandura-Version`. |
- | `api.supported_versions[]` | array | Mỗi phần tử có `version`, `released_at`, `deprecated_at` (hoặc null), `sunset_at` (hoặc null), `summary`. |
- | `key.scopes[]` | mảng string | Scope của key đang gọi. |
+ | `api.version_header` | string | Tên header phiên bản, `Wandura-Version`. |
+ | `api.supported_versions` | array | Các phiên bản ngày dùng được hôm nay. |
+ | `key.scopes` | mảng string | Scope của key đang gọi. |
+ | `key.test_organisation` | boolean | `true` khi key đang gọi thuộc một tổ chức thử (lưu lượng của nó không tính là lượt xem hay usage, và nó được gửi `Wandura-Simulate`). |
  | `rate_limits.window_seconds` | integer | Độ dài cửa sổ đếm, tính bằng giây. |
- | `rate_limits.doors.<tên>` | object | Theo nhóm endpoint (`catalog`, `playback`, `creatives`, `videos`, `config`): `limit` — trần áp cho tổ chức của bạn trong một cửa sổ (null = không có trần) — và `unit` (`tickets` cho playback, mỗi tập trong một lô tính một; còn lại là `requests`). Xem [Rate limit](../concepts/rate-limits.md). |
- | `playback.domains[]` | mảng string | Tên miền mà URL phát của bạn dùng. |
- | `playback.protection[]` | mảng string | Mức bảo vệ tổ chức của bạn có thể nhận (xem [Playback](../concepts/playback.md)). |
- | `playback.grant_ttl_seconds` | integer | Thời gian sống của một play token. |
- | `playback.manifest_url_ttl_seconds` | integer | Thời gian sống của một manifest URL đã ký. |
- | `playback.batch.max_episodes` | integer | Số tập nhiều nhất một lần gọi [Xin playback](playback.md) được xin. |
- | `playback.batch.max_next` | integer | Giá trị `next` lớn nhất trong một lần gọi. |
+ | `rate_limits.doors` | object | Theo nhóm endpoint: `catalog`, `playback`, `creatives`, `videos`, `config`. |
+ | `playback.domains` | mảng string | Tên miền mà URL phát của bạn dùng. |
+ | `playback.protection` | mảng string | Mức bảo vệ tổ chức của bạn có thể nhận. |
+ | `playback.grant_ttl_seconds` | integer | Thời gian sống của play token, tính bằng giây. |
+ | `playback.manifest_url_ttl_seconds` | integer | Thời gian sống của manifest URL đã ký, tính bằng giây. |
+ | `playback.batch.max_episodes` | integer | Số tập nhiều nhất một lần gọi playback được xin. |
+ | `playback.batch.max_next` | integer | Giá trị `next` lớn nhất trong một lần gọi playback. |
  | `subtitles.format` | string | `webvtt`. |
- | `subtitles.languages[]` | mảng string | Ngôn ngữ phụ đề đang có trên phim bạn được cấp phép. Cập nhật trong vòng 5 phút. |
- | `deprecations[]` | array | Mọi thông báo ngừng hỗ trợ: `id`, `endpoint`, `field` (null = cả endpoint), `deprecated_at`, `sunset_at`, `replacement`, `info_url`, `summary`. |
+ | `subtitles.languages` | mảng string | Ngôn ngữ phụ đề đang có trên phim bạn được cấp phép (cập nhật trong vòng 5 phút). |
+ | `deprecations` | array | Mọi thông báo ngừng hỗ trợ. Rỗng khi không có. |
  | `links` | object | URL tuyệt đối: `self`, mọi endpoint, `docs`, `evolution` và `changes` (changelog cho máy đọc). |
  
- ### Ví dụ response
+ ## Ví dụ response {#response-example}
  
  ```json
⋯
      "version_header": "Wandura-Version",
      "supported_versions": [
-       { "version": "2026-10-02", "released_at": "2026-10-02", "deprecated_at": null, "sunset_at": null, "summary": "First dated version: the /v1 response shapes as of 2 October 2026." }
+       {
+         "version": "2026-10-02",
+         "released_at": "2026-10-02",
+         "deprecated_at": null,
+         "sunset_at": null,
+         "summary": "First dated version: the /v1 response shapes as of 2 October 2026."
+       }
      ]
    },
⋯
  ```
  
- ## Lỗi {#errors}
+ ## Header của response {#response-headers}
  
- Khuôn phẳng: `{ "error": "…", "error_code": "…" }`. Xem [Lỗi](../concepts/errors.md).
+ | Header | Response | Mô tả |
+ |---|---|---|
+ | `Wandura-API-Status` | mọi response | Trạng thái API. Hiện là `beta`, ở mọi response, thành công hay lỗi. |
+ | `Wandura-Version` | mọi response | Phiên bản API theo ngày (YYYY-MM-DD) mà response này dùng: bản ghim vào API key của bạn, hoặc bản bạn gửi trong header request `Wandura-Version`. Key tạo trước khi có phiên bản ngày dùng `2026-10-02`. |
+ | `Deprecation` | 200 | Chỉ có khi endpoint này, hoặc phiên bản ngày đang phục vụ response, đã bị ngừng hỗ trợ (RFC 9745): `@<giây unix>` của ngày ngừng. Hãy ghi nó vào hệ giám sát. |
+ | `Sunset` | 200 | Chỉ có khi endpoint hay phiên bản ngày đã bị ngừng có ngày thôi chạy (RFC 8594), dạng ngày HTTP. |
+ | `Link` | 200 | Có kèm `Deprecation`: `<https://docs.wandura.ai/…>; rel="deprecation"` (và `rel="sunset"`) trỏ tới trang giải thích dùng gì thay thế. |
+ | `Cache-Control` | 200 | Luôn là `no-store`. Đừng lưu các response này trong cache dùng chung. |
+ | `Retry-After` | 429, 503 | Số giây cần chờ trước khi thử lại. Có ở response 429 và các response 503 nên thử lại. |
+ | `X-RateLimit-Limit` | 429 | Số request (với playback là số vé) được phép trong một cửa sổ cho nhóm endpoint này và tổ chức của bạn. |
+ | `X-RateLimit-Window` | 429 | Độ dài cửa sổ tính bằng giây. |
  
- | HTTP | `error_code` | Khi nào |
+ ## Lỗi {#errors}
+ 
+ | Status | `error_code` | Khi nào |
  |---|---|---|
- | 400 | `unsupported_version` | Header `Wandura-Version`, hoặc bản ghim của key, là bản lạ hay đã ngừng. Body có thêm `supported_versions` và `latest_version`. |
- | 401 | không có | Thiếu key, key lạ hoặc đã thu hồi. |
- | 403 | không có | Tổ chức của bạn đang bị tạm ngưng (`error` là `org_suspended`). |
- | 429 | `rate_limited` | Tổ chức của bạn chạm trần `config`. Chờ `Retry-After` giây. |
- | 503 | `service_unavailable` | Không kiểm được key kịp lúc. Thử lại sau `Retry-After` giây. |
+ | 400 | `unsupported_version` | Header `Wandura-Version`, hoặc bản ghim của key, là bản lạ hay đã ngừng. Body có thêm `supported_versions` và `latest_version` (và `upgrade_to` khi bản ghim đã ngừng). |
+ | 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ó (`error` là `org_suspended`) | Quyền truy cập của tổ chức bạn đang bị tạm ngưng. |
+ | 429 | `rate_limited` | Đã chạm rate limit của endpoint cấu hình. |
+ | 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` | Wandura chưa đọc được cấu hình của bạn kịp thời (`Could not read your configuration in time — retry`). Thử lại sau số giây trong `Retry-After`, có backoff. |
+ 
+ `rate_limits.doors` liệt kê mọi bộ đếm trừ bộ đếm của [Lấy một video mở](videos-get.md); toàn bộ bộ đếm nằm ở [Hành vi chuẩn của API](behaviour.md#rate-limits).
+ 
+ Cách xử lý từng lỗi: [Lỗi](../concepts/errors.md).

02/10/2026 · +1 −1 dòng

Xem thay đổi

  # Lấy cấu hình
  
- **Đang triển khai.** Trả về cấu hình áp cho API key đang gọi và tổ chức của nó: rate limit, tên miền phát, giới hạn lô, ngôn ngữ phụ đề, phiên bản API và các thông báo ngừng hỗ trợ. Đọc nó khi backend khởi động, hoặc vài giờ một lần, thay vì viết cứng các giá trị này. Xem [API tiến hoá](../concepts/api-evolution.md#config).
+ Trả về cấu hình áp cho API key đang gọi và tổ chức của nó: rate limit, tên miền phát, giới hạn lô, ngôn ngữ phụ đề, phiên bản API và các thông báo ngừng hỗ trợ. Đọc nó khi backend khởi động, hoặc vài giờ một lần, thay vì viết cứng các giá trị này. Xem [API tiến hoá](../concepts/api-evolution.md#config).
  
  ```
⋯

02/10/2026 · Tạo trang