Lấy catalog được cấp phép

Trả về mọi phim và tập mà tổ chức của bạn được phép stream ngay lúc này. Response chỉ có metadata và không bao giờ chứa URL video; hãy xin playback cho từng tập bằng Xin playback.

GET /api/delivery/v1/catalog

Scope: metadata:read

Mô tả

Một phim được đưa vào khi tổ chức của bạn có giấy phép streaming đang hoạt động cho phim đó, hôm nay (theo UTC) nằm trong khung thời gian của giấy phép, và phim đã được publish. Với mỗi phim được đưa vào, mọi tập đã publish đều được trả về, cộng thêm một dòng placeholder cho mỗi tập dự kiến chưa publish. Phim được sắp theo display_order. Không có limit và cursor thì bạn nhận cả catalog trong một response; có limit thì bạn nhận các trang phim, mỗi trang kèm mọi tập của các phim đó, cho đến khi next_cursor là null. Các trang không phải một ảnh chụp nhất quán: hãy đọc Hành vi chuẩn của API · Phân trang trước khi phân trang. Xem Catalog.

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 `metadata:read`.
`limit`	query	integer	Không	Tuỳ chọn. Số phim mỗi trang, từ 1 đến 200. Bỏ trống (cùng `cursor`) để nhận cả catalog trong một response.
`cursor`	query	string	Không	Tuỳ chọn. `next_cursor` (hoặc cursor trong `links.next`) của trang trước. Opaque; truyền lại nguyên vẹn. Có cursor mà không có `limit` thì mỗi trang 50 phim.
`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/catalog \
  -H "Authorization: Bearer $WANDURA_API_KEY"

Response

200 OK với một object chứa hai mảng.

Trường của phim (`films[]`)

Trường	Kiểu	Mô tả
`id`	string (UUID)	Film ID. Không bao giờ đổi: dùng làm khoá chính bên bạn, và làm `film_ref` khi xin playback.
`title`	string	Tên phim.
`slug`	string	Định danh phim an toàn cho URL, không trùng giữa các phim. Wandura không đổi nó sau khi tạo phim. Cũng được chấp nhận làm `film_ref` khi xin playback.
`synopsis_short`	string hoặc null	Mô tả ngắn cho thẻ. Độ dài không cố định.
`synopsis_full`	string hoặc null	Mô tả đầy đủ cho trang chi tiết.
`genres`	mảng string	Nhãn thể loại. Có thể rỗng.
`language`	string hoặc null	Ngôn ngữ của phim, là chữ tự do do đội nội dung Wandura ghi (ví dụ `en` hoặc `English`). Không phải danh sách mã cố định: hiển thị nguyên, đừng phân tích.
`poster_url`	string hoặc null	URL poster phim.
`status`	string	Luôn là `published`.
`display_order`	integer	Vị trí hiển thị, nhỏ nhất trước. Mảng đã được sắp theo trường này.
`planned_episodes`	integer hoặc null	Tổng số tập dự kiến. `null` khi chưa đặt: khi đó phim không có dòng placeholder nào, và `episodes` chỉ liệt kê các tập đã phát hành.
`free_until_episode`	integer hoặc null	Các tập có `episode_no` nhỏ hơn hoặc bằng số này là miễn phí. `0` nghĩa là không có tập miễn phí. `null` nghĩa là phim chưa được đặt số này: coi mọi tập là trả phí, và hỏi Wandura nếu bạn nghĩ phim có tập miễn phí.
`audience`	string hoặc null	`women`, `men`, `lgbtq`, hoặc `null` nếu chưa phân loại. Có thể có giá trị mới.
`form`	string hoặc null	`live_action`, `anime`, hoặc `null` nếu chưa phân loại. Có thể có giá trị mới.
`setting`	string hoặc null	`modern`, `city`, `fantasy`, `campus`, `palace`, hoặc `null` nếu chưa phân loại. Có thể có giá trị mới.
`images`	array	Ảnh của phim, mỗi loại Wandura có là một phần tử. Loại Wandura chưa có thì không có mặt (không bao giờ là phần tử `null`), nên mảng có thể rỗng. Mọi `url` là URL `https` tuyệt đối trên host của Wandura, tải thẳng được. `poster_url` giữ nguyên như cũ.

Trường của tập (`episodes[]`)

Trường	Kiểu	Mô tả
`id`	string (UUID) hoặc null	Episode ID. Dùng làm `episode_id` khi xin playback. `null` ở dòng placeholder.
`film_id`	string (UUID)	ID của phim mà tập thuộc về.
`episode_no`	integer	Số tập, bắt đầu từ 1.
`title`	string hoặc null	Tên tập.
`synopsis`	string hoặc null	Mô tả tập. Thường là `null`.
`duration_ms`	integer hoặc null	Thời lượng tính bằng mili giây.
`poster_uri`	string hoặc null	Tham chiếu tới ảnh thumbnail của tập. Không đảm bảo là URL tải trực tiếp được — dùng `poster_url`.
`poster_url`	string hoặc null	Ảnh tập dạng URL `https` tuyệt đối tải thẳng được, hoặc `null` (khi đó dùng `poster_url` của phim).
`status`	string	`published`, hoặc `planned` với dòng placeholder.
`stream_ready`	boolean	`true` khi có thể cấp vé cho tập. Luôn là `false` ở dòng placeholder.

Trong một phim, mỗi episode_no chỉ xuất hiện một lần, nên film_id + episode_no xác định một tập. Các tập được nhóm theo film ID và sắp theo episode_no trong mỗi phim. Hãy lấy thứ tự phim từ films.

Nếu tổ chức của bạn hiện không có giấy phép nào, cả hai mảng đều rỗng.

Ví dụ response

{
  "films": [
    {
      "id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10",
      "title": "The Heiress Returns",
      "slug": "the-heiress-returns",
      "synopsis_short": "Cast out on her wedding day, a disowned heiress comes back to take everything.",
      "synopsis_full": "Cast out on her wedding day, Mia loses her family, her name and her fortune. Five years later she returns with a new identity and one goal.",
      "genres": ["romance", "revenge"],
      "language": "en",
      "poster_url": "https://cdn.example.com/posters/the-heiress-returns.jpg",
      "status": "published",
      "display_order": 10,
      "planned_episodes": 3,
      "free_until_episode": 1,
      "audience": "women",
      "form": "live_action",
      "setting": "modern",
      "images": [
        { "kind": "poster_3_4", "url": "https://cdn.example.com/posters/the-heiress-returns-3x4.jpg", "width": 1080, "height": 1440 },
        { "kind": "cover_9_16", "url": "https://cdn.example.com/posters/the-heiress-returns.jpg", "width": null, "height": null }
      ]
    }
  ],
  "episodes": [
    {
      "id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e",
      "film_id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10",
      "episode_no": 1,
      "title": "Episode 1",
      "synopsis": null,
      "duration_ms": 94000,
      "poster_uri": null,
      "status": "published",
      "stream_ready": true
    },
    {
      "id": "c7d9e1f3-5a6b-4c8d-9e0f-1a2b3c4d5e6f",
      "film_id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10",
      "episode_no": 2,
      "title": "Episode 2",
      "synopsis": null,
      "duration_ms": 101000,
      "poster_uri": null,
      "status": "published",
      "stream_ready": false
    },
    {
      "id": null,
      "film_id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10",
      "episode_no": 3,
      "title": null,
      "synopsis": null,
      "duration_ms": null,
      "poster_uri": null,
      "status": "planned",
      "stream_ready": false
    }
  ]
}

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.
`Cache-Control`	mọi response	Luôn là `no-store`. Đừng lưu các response này trong cache dùng chung.
`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ế.
`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	`invalid_request`	`limit` không phải số nguyên từ 1 đến 200, hoặc `cursor` không phải giá trị endpoint này trả về.
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ó	Key thiếu scope `metadata:read`.
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 catalog.
503	`service_unavailable`	Wandura chưa kiểm được API key hoặc chưa đọc được catalog kịp thời. Phía bạn không sai gì: thử lại sau số giây trong `Retry-After`, có backoff.

Hai response 403 không có error_code. Phân biệt bằng error: đúng bằng org_suspended khi tổ chức bạn bị tạm ngưng, còn chữ khác nghĩa là key thiếu metadata:read. Đây là trường hợp duy nhất bạn so error; hãy so nguyên chuỗi.

Cách xử lý từng trường hợp: Lỗi.

Lấy catalog được cấp phép

Mô tả#

Tham số request#

Ví dụ request#

Response#

Trường của phim (films[])#

Trường của tập (episodes[])#

Ví dụ response#

Header của response#

Lỗi#