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

WanduraDocsBeta

API v2

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

Liệt kê video mở

Trên trang này

Tham số request
Ví dụ request
Response
Các trường của một video (rows[])
Ví dụ response
Header của response
Lỗi

Đường này đã đóng băng. Nó vẫn chạy và app đang dùng không phải đổi gì, nhưng Wandura không phát triển thêm tính năng cho nó. Tích hợp mới nên đi theo Kho video riêng, nơi app của bạn đọc thẳng từ nền tảng video trong kho của tổ chức mình.

Trả về một trang các video mở được cấp cho tổ chức của bạn, mỗi video kèm link MP4 đã ký có hiệu lực 1 giờ. Hãy duyệt hết mọi trang và cache kết quả trên server của bạn. Xem Video mở và Đồng bộ video mở.

GET /api/delivery/v1/videos

Scope: videos:read, trên một key gắn với một app

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 `videos:read`.
`collection`	query	string	Không	Chỉ lấy một bộ sưu tập, theo mã của bộ.
`cursor`	query	string	Không	Token opaque lấy từ `next_cursor` trước đó. Đừng tự dựng hay phân tích nó.
`limit`	query	integer	Không	Số dòng mỗi trang, từ 1 đến 200. Mặc định `50`.
`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`.

Ví dụ request

curl -s "https://www.wandura.ai/api/delivery/v1/videos?limit=50" \
  -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ả
`rows`	array	Các video trên trang này, theo thứ tự của bộ sưu tập.
`next_cursor`	string hoặc null	Truyền làm `cursor` để lấy trang kế. `null` nghĩa là bạn đã có đủ.
`expires_at`	string (ISO 8601, UTC)	Thời điểm mọi link trên trang này ngừng chạy (1 giờ sau response).
`refresh_before`	string (ISO 8601, UTC)	Gọi lại danh sách trước thời điểm này (45 phút sau response).
`links`	object	URL tuyệt đối dựng sẵn — đi theo `links.next` thay vì tự ráp URL trang kế.
`links.self`	string	Chính request này.
`links.next`	string hoặc null	Trang sau, hoặc `null` ở trang cuối.

Các trường của một video (`rows[]`)

Trường	Kiểu	Mô tả
`id`	string (UUID)	Video ID. Không bao giờ đổi; đồng bộ theo trường này.
`slug`	string	Định danh video an toàn cho URL.
`title`	string	Tên video.
`order_code`	string hoặc null	Mã đơn sản xuất (ví dụ `ABS_01_E01`), khớp từng ký tự với file đặt hàng của bạn, hoặc `null` với video không có trong đó. Dùng nó để ghép một lần với file đặt hàng.
`collection`	string	Mã bộ sưu tập của dòng này. Video thuộc hai bộ được cấp sẽ xuất hiện một lần dưới mỗi bộ.
`position`	integer	Vị trí của video trong bộ sưu tập. Các dòng trả về theo thứ tự của bộ.
`duration_ms`	integer hoặc null	Thời lượng tính bằng mili giây.
`muscle_groups`	mảng string	Nhóm cơ được tập. Có thể rỗng.
`equipment`	mảng string	Dụng cụ cần có. Có thể rỗng.
`difficulty`	string hoặc null	Nhãn độ khó.
`kcal_est`	integer hoặc null	Lượng calo ước tính tiêu hao.
`mp4`	object	Link MP4 đã ký, dùng được tới `expires_at`. Phát nguyên như nhận được; đừng lưu chúng trong app.
`mp4.p480`	string	Link MP4 480p. Mặc định phát bản này.
`mp4.p720`	string hoặc null	Link MP4 720p, hoặc `null` cho tới khi có bản này.

Dừng duyệt khi next_cursor là null, không bao giờ dừng vì một trang ngắn hay rỗng: các video chưa sẵn sàng phát bị bỏ qua.

Ví dụ response

{
  "rows": [
    {
      "id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10",
      "slug": "core-abs-01",
      "title": "Core abs 01",
      "order_code": "ABS_01_E01",
      "collection": "ABS_01",
      "position": 1,
      "duration_ms": 42000,
      "muscle_groups": ["abs"],
      "equipment": [],
      "difficulty": "beginner",
      "kcal_est": 12,
      "mp4": { "p480": "https://cdn.example.com/v/core-abs-01-480.mp4?sign=example", "p720": null }
    }
  ],
  "next_cursor": null,
  "expires_at": "2026-10-01T13:00:00.000Z",
  "refresh_before": "2026-10-01T12:45:00.000Z"
}

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	không có	`cursor` không phải token do endpoint này cấp, hoặc `limit` không phải số nguyên từ 1 đến 200.
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 `videos:read`.
403	không có (`error` là `app_not_registered`)	Key chưa gắn với app nào. Đăng ký app ở trang Developers rồi dùng key của app đó.
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.
404	không có (`error` là `collection_not_found`)	Bộ sưu tập không tồn tại, chưa publish, hoặc chưa cấp cho tổ chức của bạn.
429	`rate_limited`	Đã chạm rate limit của endpoint này.
500	không có	Không đọc được danh sách video. Retry với backoff.
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.

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

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