Bỏ qua menu, tới nội dung

WanduraDocsBeta

API v1

BetaDocs đang ở bản beta và còn thay đổi. Thấy chỗ sai, khó hiểu hoặc còn thiếu? Hãy cho chúng tôi biết.

Tài liệu tham chiếu API

Lấy cấu hình

Trên trang này

Tham số request
Ví dụ request
Response
Ví dụ response
Header của response
Lỗi

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.

GET /api/delivery/v1/config

Scope: mọi API key hợp lệ

Tham số request

Tên	Vị trí	Kiểu	Bắt buộc	Mô tả
`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

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

Response

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à 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	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`	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ợ. 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

{
  "api": {
    "status": "beta",
    "path_version": "v1",
    "version": "2026-10-02",
    "pinned_version": "2026-10-02",
    "latest_version": "2026-10-02",
    "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."
      }
    ]
  },
  "key": { "scopes": ["metadata:read", "playback"] },
  "rate_limits": {
    "window_seconds": 60,
    "doors": {
      "catalog": { "limit": 3000, "unit": "requests" },
      "playback": { "limit": 10800, "unit": "tickets" },
      "creatives": { "limit": 3000, "unit": "requests" },
      "videos": { "limit": 3000, "unit": "requests" },
      "config": { "limit": 600, "unit": "requests" }
    }
  },
  "playback": {
    "domains": ["playback.example.com"],
    "protection": ["private-encrypted"],
    "grant_ttl_seconds": 1800,
    "manifest_url_ttl_seconds": 900,
    "batch": { "max_episodes": 3, "max_next": 2 }
  },
  "subtitles": { "format": "webvtt", "languages": ["en"] },
  "deprecations": [],
  "links": {
    "self": "https://www.wandura.ai/api/delivery/v1/config",
    "catalog": "https://www.wandura.ai/api/delivery/v1/catalog",
    "playback": "https://www.wandura.ai/api/delivery/v1/playback",
    "creatives": "https://www.wandura.ai/api/delivery/v1/creatives",
    "videos": "https://www.wandura.ai/api/delivery/v1/videos",
    "config": "https://www.wandura.ai/api/delivery/v1/config",
    "docs": "https://docs.wandura.ai/developers/reference/overview",
    "evolution": "https://docs.wandura.ai/developers/concepts/api-evolution",
    "changes": "https://docs.wandura.ai/changes.json"
  }
}

Header của response

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`.
`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`	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.
`X-RateLimit-Window`	429	Độ dài cửa sổ tính bằng giây.

Lỗi

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` (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ở; toàn bộ bộ đếm nằm ở Hành vi chuẩn của API.

Cách xử lý từng lỗi: Lỗi.

Cập nhật 05/10/2026 · Lịch sử thay đổi (4)