Lịch sử: Tài liệu tham chiếu API

Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.

01/10/2026 · +3 −3 dòng

Xem thay đổi

⋯
  | `creatives:export` | [Liệt kê creative](creatives-list.md), [Lấy một creative](creatives-get.md) | Tự tạo trên partner portal |
  | `webhooks:manage` | Chưa có endpoint nào dùng | Tự tạo trên partner portal |
- | `playback` | [Xin playback](playback.md) | Chỉ Wandura cấp |
+ | `playback` | [Xin playback](playback.md) | Tự tạo trên partner portal (**Stream films in an app**) |
  
- Thành viên tổ chức có vai trò **Admin** hoặc **Developer** tạo, xoay vòng và thu hồi key trên trang **Developers** của partner portal. Key đầy đủ chỉ hiện một lần, lúc tạo. Key có scope `playback` do Wandura quản lý và không xoay vòng được từ portal. Xem [Xác thực](../authentication.md).
+ Thành viên tổ chức có vai trò **Admin** hoặc **Developer** tạo, xoay vòng và thu hồi key trên trang **Developers** của partner portal. Key đầy đủ chỉ hiện một lần, lúc tạo. Kể cả key có scope `playback`: nếu key bị lộ, bất kỳ ai cũng stream được phim bạn được cấp phép, nên hãy thu hồi ngay. Xem [Xác thực](../authentication.md).
  
  ## Phiên bản
⋯
  ## Rate limit
  
- Mỗi tổ chức có một ngưỡng chống lạm dụng cho từng nhóm endpoint, đếm trong một cửa sổ cố định 60 giây: 30.000 request playback, và 3.000 request dùng chung cho endpoint catalog và creatives. Ngưỡng này cao hơn rất nhiều so với lưu lượng bình thường, nên chạm ngưỡng thường có nghĩa là có vòng lặp chạy mất kiểm soát. Wandura nâng được ngưỡng khi bạn yêu cầu. Các header giới hạn dưới đây chỉ xuất hiện trên response `429`.
+ Mỗi tổ chức có một ngưỡng chống lạm dụng cho từng nhóm endpoint, đếm trong một cửa sổ cố định 60 giây: 10.800 request playback (khoảng 180 vé mỗi giây), 3.000 request catalog và 3.000 request creatives, mỗi nhóm một bộ đếm riêng. Chạm ngưỡng thường có nghĩa là có vòng lặp chạy mất kiểm soát. Wandura nâng được bất kỳ ngưỡng nào riêng cho tổ chức của bạn khi bạn yêu cầu, có hiệu lực trong khoảng một phút. Các header giới hạn dưới đây chỉ xuất hiện trên response `429`.
  
  Khi bạn chạm ngưỡng, mọi endpoint, kể cả endpoint creatives, đều trả `429` với body phẳng:
⋯

01/10/2026 · +5 −3 dòng

Xem thay đổi

⋯
  | `GET` | `/api/delivery/v1/creatives/{id}` | `creatives:export` | [Lấy một creative](creatives-get.md) |
  
+ Mọi đường dẫn khác dưới `/api/delivery/v1/`, với bất kỳ method nào, trả `404` kèm body JSON phẳng và `error_code` `not_found`. Nếu gặp nó ở một đường dẫn bạn tưởng là đúng, hãy soát lỗi gõ trong đường dẫn.
+ 
  ## Chỉ server-to-server
  
⋯
  | Trường | Kiểu | Mô tả |
  |---|---|---|
- | `error` | string | Thông điệp cho người đọc. Đừng parse. |
+ | `error` | string | Thông điệp cho người đọc. Đừng parse. Một ngoại lệ: `403` của catalog không có `error_code`, và `error` đúng bằng `org_suspended` khi tổ chức bạn bị tạm ngưng. Xem [Liệt kê catalog có giấy phép](catalog.md#errors). |
  | `error_code` | string | Mã máy đọc được. Rẽ nhánh theo trường này. Một số lỗi không có trường này, ví dụ `401`. |
  | `reason` | string | Có mặt cùng `not_entitled`. Lý do chi tiết, dùng cho log và hỗ trợ. |
⋯
  ## Rate limit
  
- Mỗi tổ chức có một ngưỡng chống lạm dụng cho từng nhóm endpoint, đếm trong một cửa sổ thời gian cố định. Ngưỡng này cao hơn rất nhiều so với lưu lượng bình thường, nên chạm ngưỡng thường có nghĩa là có vòng lặp chạy mất kiểm soát. Endpoint catalog và creatives dùng chung một bộ đếm; playback có bộ đếm riêng.
+ Mỗi tổ chức có một ngưỡng chống lạm dụng cho từng nhóm endpoint, đếm trong một cửa sổ cố định 60 giây: 30.000 request playback, và 3.000 request dùng chung cho endpoint catalog và creatives. Ngưỡng này cao hơn rất nhiều so với lưu lượng bình thường, nên chạm ngưỡng thường có nghĩa là có vòng lặp chạy mất kiểm soát. Wandura nâng được ngưỡng khi bạn yêu cầu. Các header giới hạn dưới đây chỉ xuất hiện trên response `429`.
  
  Khi bạn chạm ngưỡng, mọi endpoint, kể cả endpoint creatives, đều trả `429` với body phẳng:
⋯
  | `X-RateLimit-Window` | Độ dài cửa sổ tính bằng giây. |
  
- Chờ hết `Retry-After` rồi mới retry. Xem [Rate limit](../concepts/rate-limits.md).
+ Chờ hết `Retry-After` rồi mới retry. Xem [Rate limit](../concepts/rate-limits.md#limits).

01/10/2026 · +1 −1 dòng

Xem thay đổi

⋯
  ## Phiên bản
  
- Phiên bản API nằm trong path (`/v1`). Trong cùng một phiên bản, Wandura có thể thêm trường response mới và mã lỗi mới mà không báo trước. Hãy bỏ qua các trường bạn không nhận ra, và luôn có nhánh mặc định cho mã lỗi lạ.
+ Phiên bản API nằm trong path (`/v1`). Trong cùng một phiên bản, Wandura có thể thêm trường response mới và mã lỗi mới mà không báo trước. Hãy bỏ qua các trường bạn không nhận ra, và luôn có nhánh mặc định cho mã lỗi lạ. Thế nào là phá vỡ tương thích, và phiên bản cũ được hỗ trợ bao lâu: [Phiên bản và ngừng hỗ trợ](../concepts/versioning.md).
  
  Bản ghi creative còn mang trường `schema_version`, hiện là `1`. Trường được bổ sung thêm không làm thay đổi giá trị này.
⋯

01/10/2026 · +4 −0 dòng

Xem thay đổi

⋯
  Bản ghi creative còn mang trường `schema_version`, hiện là `1`. Trường được bổ sung thêm không làm thay đổi giá trị này.
  
+ ### Beta {#beta}
+ 
+ API đang ở bản **beta**. Mọi response từ `/v1` đều mang header `Wandura-API-Status: beta`. Trong giai đoạn beta, Wandura vẫn có thể đổi cách hoạt động bên trong `/v1`; các thay đổi được ghi ở **Nhật ký thay đổi** (link cuối mọi trang). Thấy chỗ sai hoặc thiếu? Bấm **Gửi góp ý** ở đầu mọi trang docs.
+ 
  ## Request và response
  
⋯

29/09/2026 · Tạo trang