Bản lưu ngày / Snapshot of 2026-10-10 · Xem bản mới nhất / See the latest version
WanduraDocsBeta
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.
Bạn đang đọc một bản tài liệu cũ: v1 · Sang bản mới nhất (v2)
Tài liệu tham chiếu API

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

Markdown
Trên trang này

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.
code string hoặc null Mã bộ của Wandura, ví dụ WD000016. Ổn định và dùng chung trong mọi hệ thống của Wandura (playlist trong media space của bạn mang đúng tên này). Dùng nó với GET /api/delivery/v1/series/{code}.
title_i18n object Chữ theo ngôn ngữ: khoá là mã BCP-47, giá trị là chữ, ví dụ {"en": "The Heiress Returns"}. Hiện Wandura điền en; có thể có thêm ngôn ngữ. Thiếu khoá nghĩa là chưa có chữ ngôn ngữ đó: lùi về en. Object rỗng khi không có chữ.
synopsis_short_i18n object Chữ theo ngôn ngữ: khoá là mã BCP-47, giá trị là chữ, ví dụ {"en": "The Heiress Returns"}. Hiện Wandura điền en; có thể có thêm ngôn ngữ. Thiếu khoá nghĩa là chưa có chữ ngôn ngữ đó: lùi về en. Object rỗng khi không có chữ.
synopsis_i18n object Chữ theo ngôn ngữ: khoá là mã BCP-47, giá trị là chữ, ví dụ {"en": "The Heiress Returns"}. Hiện Wandura điền en; có thể có thêm ngôn ngữ. Thiếu khoá nghĩa là chưa có chữ ngôn ngữ đó: lùi về en. Object rỗng khi không có chữ.
content_rating string hoặc null Độ tuổi: all, 13+, 16+ hoặc 18+. null khi chưa chấm.
is_completed boolean hoặc null true khi mọi tập dự kiến đã ra, false khi còn tập sắp ra, null khi chưa biết tổng số tập dự kiến.
release_date string hoặc null Ngày phát hành gốc, YYYY-MM-DD, hoặc null khi chưa biết.
default_lang string hoặc null Ngôn ngữ âm thanh của phim dạng mã BCP-47 (en, vi, pt-BR), hoặc null khi chưa biết. Nên dùng trường này thay cho language (chữ tự do).
tags array Thẻ thể loại và chủ đề có mã. Tối đa một thẻ có is_main là true (thể loại chính, hiện dưới tên phim). Có thể rỗng.
people array Diễn viên hoặc nhân vật chính, vai chính trước. Có thể rỗng.
trailer object hoặc null Video trailer, hoặc null. vid là video ID trong media space của Wandura.
metadata_version string hoặc null Mã băm metadata của phim (tên, tóm tắt, độ tuổi, thẻ, người, ảnh, các tập và phụ đề). Băm không đổi = bên bạn không có gì phải cập nhật.
metadata_updated_at string (ISO 8601, UTC) hoặc null Lúc metadata_version đổi lần gần nhất.
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.
title_i18n object Chữ theo ngôn ngữ: khoá là mã BCP-47, giá trị là chữ, ví dụ {"en": "The Heiress Returns"}. Hiện Wandura điền en; có thể có thêm ngôn ngữ. Thiếu khoá nghĩa là chưa có chữ ngôn ngữ đó: lùi về en. Object rỗng khi không có chữ.
subtitles array Các ngôn ngữ phụ đề có cho tập (file đi kèm vé playback). Rỗng ở dòng placeholder.
subtitles[].lang string Mã BCP-47, ví dụ en.

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",
      "code": "WD000016",
      "title_i18n": { "en": "The Heiress Returns" },
      "synopsis_short_i18n": { "en": "Cast out on her wedding day, a disowned heiress comes back to take everything." },
      "synopsis_i18n": { "en": "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." },
      "content_rating": "13+",
      "is_completed": false,
      "release_date": null,
      "default_lang": "en",
      "tags": [
        { "slug": "revenge", "name": "Revenge", "name_i18n": { "en": "Revenge" }, "type": "genre", "is_main": true },
        { "slug": "romance", "name": "Romance", "name_i18n": { "en": "Romance" }, "type": "genre", "is_main": false },
        { "slug": "heiress", "name": "Heiress", "name_i18n": { "en": "Heiress" }, "type": "theme", "is_main": false }
      ],
      "people": [{ "name": "Mia", "role": "lead", "description": "A disowned heiress back for what is hers.", "avatar_url": null }],
      "trailer": null,
      "metadata_version": "9a0b1c2d3e4f5061728394a5b6c7d8e9",
      "metadata_updated_at": "2026-10-03T09:00:00.000Z",
      "images": [
        { "kind": "poster_3_4", "lang": null, "url": "https://cdn.example.com/posters/the-heiress-returns-3x4.jpg", "width": 1080, "height": 1440 },
        { "kind": "cover_9_16", "lang": null, "url": "https://cdn.example.com/posters/the-heiress-returns.jpg", "width": 1080, "height": 1920 }
      ]
    }
  ],
  "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,
      "title_i18n": { "en": "Episode 1" },
      "subtitles": [{ "lang": "en" }]
    },
    {
      "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.

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

↑↓ chọnEnter mởEsc đóng

Gửi góp ý

Góp ý được gửi thẳng tới đội Wandura, kèm địa chỉ trang này.

0 / 4000