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ó pagination. Xem Catalog.

Tham số request

Tên	Vị trí	Kiểu	Bắt buộc	Mô tả
`Authorization`	header	string	Có	`Bearer <API key>`.

Endpoint này không nhận query parameter nào.

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.
`form`	string hoặc null	`live_action`, `anime`, hoặc `null` nếu chưa phân loại.
`setting`	string hoặc null	`modern`, `city`, `fantasy`, `campus`, `palace`, hoặc `null` nếu chưa phân loại.

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.
`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"
    }
  ],
  "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
    }
  ]
}

Lỗi

Status	`error_code`	Khi nào
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 endpoint catalog và creatives.
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.

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.

Xem Lỗi để biết cách xử lý từng trường hợp.

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#

Lỗi#