Lịch sử thay đổi
Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.
- 05/10/2026 · +6 −0 dòng
Xem thay đổi
⋯ Không bao giờ diễn ra âm thầm: xoá hoặc đổi tên endpoint, tham số hay trường; thêm tham số bắt buộc; đổi kiểu hay ý nghĩa của một trường; đổi cách xác thực hoặc scope mà endpoint cần; trả mã lỗi khác cho một trường hợp đã có; hạ rate limit. Chúng được phát hành thành phiên bản theo ngày mới, hoặc phiên bản lớn mới, hoặc trong giai đoạn beta thì theo [quy tắc beta](#beta). + ## Tài liệu của bản trước {#older-docs} + + Khi Wandura ra một bản tài liệu lớn mới, bản trước **được giữ nguyên**, không bị xoá: đọc ở `/vi/v1/developers/…` (bản tiếng Anh ở `/v1/developers/…`), có băng báo "bản cũ" ở đầu trang. Bản đã đóng băng không sửa nữa, trừ lỗi bảo mật. Nếu tích hợp của bạn đang chạy theo bản cũ, đó vẫn là tài liệu đúng cho bạn. + + **Số bản tài liệu không phải số trong đường dẫn API.** Bản tài liệu hiện hành là **v2** vì mô hình tích hợp đã đổi (kho riêng của tổ chức bạn), nhưng các endpoint REST vẫn giữ nguyên `/api/delivery/v1/…`. Đừng đi tìm `/api/delivery/v2`. + ## Phiên bản theo ngày {#dated-versions} ⋯
- 02/10/2026 · +67 −32 dòng
Xem thay đổi
- # Phiên bản và ngừng hỗ trợ + # Phiên bản và API tiến hoá - > **TL;DR** — Phiên bản nằm trong path (`/v1`). Thay đổi bổ sung được phát hành không báo trước. Thay đổi phá vỡ tương thích được phát hành ở phiên bản mới, và phiên bản cũ vẫn chạy **12 tháng** kể từ khi công bố phiên bản mới. Trong giai đoạn beta, thay đổi phá vỡ tương thích bên trong `/v1` được báo trước ít nhất **30 ngày**, trừ bản vá bảo mật khẩn. + > **TL;DR** — Phiên bản lớn nằm trong path (`/v1`). Bên trong đó, Wandura chỉ **thêm**; mọi thay đổi hình dạng được phát hành thành một **phiên bản theo ngày** mới, và key của bạn vẫn ghim vào phiên bản lúc nó được tạo. Đọc response một cách dễ tính (bỏ qua trường lạ, giá trị lạ = nhánh mặc định, mã lỗi lạ = xử theo nhóm status) thì tích hợp của bạn vẫn chạy mà không phải sửa code. Thay đổi phá vỡ tương thích có **12 tháng** chạy song song, hoặc báo trước **30 ngày** trong giai đoạn beta. Phiên bản theo ngày, link dựng sẵn, `GET /config` và header ngừng hỗ trợ đều đã chạy. ## Phiên bản hoạt động thế nào {#how-versions-work} - Phiên bản API là một phần của mọi path: `https://www.wandura.ai/api/delivery/v1/…`. Bạn chọn phiên bản lớn qua path bạn gọi; bạn không phải đặt header nào. Trong giai đoạn beta, mọi response từ `/v1` còn mang `Wandura-API-Status: beta`. + | Tầng | Ví dụ | Cách bạn chọn | + |---|---|---| + | Phiên bản lớn | `/api/delivery/v1/…` | Path bạn gọi. | + | Phiên bản theo ngày | `2026-10-02` | Key của bạn được ghim vào phiên bản hiện hành lúc key được tạo. Ghi đè theo từng request bằng header `Wandura-Version`. | - **Phiên bản theo ngày bên trong `/v1`.** Hình dạng response bên trong `/v1` mang thêm một ngày (ví dụ `2026-10-02`): API key của bạn được ghim vào bản hiện hành lúc tạo key, mọi response nói nó dùng bản nào trong header `Wandura-Version`, và bạn có thể thử bản mới hơn theo từng request bằng cách gửi header đó. Khi đó một thay đổi hình dạng được phát hành thành bản ngày mới, và key của bạn vẫn nhận hình cũ tới ngày tắt của bản đó. Xem [API tiến hoá](api-evolution.md#dated-versions). + Mọi response cho biết phiên bản theo ngày nào tạo ra nó trong header `Wandura-Version`, và mang `Wandura-API-Status: beta` trong lúc API còn ở bản beta. - ## Thay đổi không phá vỡ tương thích {#additive} + ## Đọc response một cách dễ tính {#tolerant-reader} - Những thay đổi này có thể xuất hiện trong phiên bản hiện tại bất cứ lúc nào, không báo trước. Hãy viết tích hợp sao cho vẫn chạy khi chúng xuất hiện: + | Bạn | Đổi lại, Wandura | + |---|---| + | **Bỏ qua các trường bạn không nhận ra.** Không bao giờ kiểm response theo một schema đóng. | Không bao giờ xoá, đổi tên hay đổi kiểu một trường bên trong một phiên bản theo ngày. | + | **Coi giá trị lạ là trường hợp chung** (với `protection`, `status`…). | Báo giá trị mới trong changelog trước khi trả về. | + | **Xử `error_code` lạ theo nhóm status**: `429` thì chờ `Retry-After`; các `4xx` khác thì không retry; `5xx` thì retry có backoff. | Không bao giờ đổi mã lỗi hay status của một trường hợp đã có. | - - Thêm endpoint mới. - - Thêm tham số request tuỳ chọn. - - Thêm trường mới trong response. Bỏ qua các trường bạn không nhận ra. - - Thêm mã lỗi mới, hoặc giá trị mới trong một trường liệt kê trạng thái. Luôn có nhánh mặc định. - - Nâng rate limit. + ## Thay đổi không phá vỡ tương thích {#additive} - Luật để tích hợp của bạn không bị ảnh hưởng nằm ở [API tiến hoá](api-evolution.md#tolerant-reader). + Chúng có thể xuất hiện bất cứ lúc nào, không báo trước: endpoint mới; tham số tuỳ chọn mới; trường response mới; mã lỗi hoặc giá trị enum mới; rate limit cao hơn. ## Thay đổi phá vỡ tương thích {#breaking} - Những thay đổi này không bao giờ diễn ra âm thầm. Chúng được phát hành ở phiên bản mới, hoặc trong giai đoạn beta thì theo [quy tắc beta](#beta): + Không bao giờ diễn ra âm thầm: xoá hoặc đổi tên endpoint, tham số hay trường; thêm tham số bắt buộc; đổi kiểu hay ý nghĩa của một trường; đổi cách xác thực hoặc scope mà endpoint cần; trả mã lỗi khác cho một trường hợp đã có; hạ rate limit. Chúng được phát hành thành phiên bản theo ngày mới, hoặc phiên bản lớn mới, hoặc trong giai đoạn beta thì theo [quy tắc beta](#beta). - - Xoá hoặc đổi tên endpoint, tham số request hay trường response. - - Thêm tham số request bắt buộc. - - Đổi kiểu dữ liệu hoặc ý nghĩa của một trường đang có. - - Đổi cách xác thực, hoặc scope mà một endpoint cần. - - Trả mã lỗi khác cho một trường hợp vốn đã có mã lỗi. - - Hạ rate limit. + ## Phiên bản theo ngày {#dated-versions} - ## Thời gian hỗ trợ {#support-window} + - **Key của bạn được ghim.** Key nhận đúng hình dạng mà bạn đã dựng theo, cho tới ngày tắt của phiên bản đó. Key tạo trước khi có phiên bản theo ngày dùng `2026-10-02`. + - **Thử phiên bản mới hơn theo từng request** bằng `Wandura-Version: <date>`. Khi code của bạn đã xử lý được, hãy chuyển key sang: key **mới** được ghim vào phiên bản mới nhất; **xoay** key thì giữ nguyên phiên bản đang ghim. + - **Phiên bản không tồn tại hoặc đã ngừng** trong header (hoặc là phiên bản key đang ghim) trả `400` `unsupported_version`, kèm `supported_versions`, `latest_version` và, với phiên bản ghim đã ngừng, `upgrade_to`. Bước kiểm tra này diễn ra trước khi kiểm key, và dùng định dạng phẳng ở mọi endpoint. + - Cách chuyển từ phiên bản này sang phiên bản kế: [Chuyển phiên bản](../guides/migrating-versions.md). - Khi một phiên bản mới (ví dụ `/v2`) được phát hành: + ### Lịch sử phiên bản {#version-history} - 1. Wandura công bố trong nhật ký thay đổi và gửi email cho Admin của mọi tổ chức đang dùng API. - 2. Phiên bản trước vẫn chạy, không đổi, trong **12 tháng** kể từ lúc công bố. - 3. Trong 12 tháng đó, tài liệu của phiên bản trước vẫn đọc được, có đánh dấu là phiên bản cũ, ở địa chỉ riêng (ví dụ `/vi/v1/developers/…`). Dùng menu phiên bản ở đầu các trang API. - 4. Hết 12 tháng, phiên bản trước ngừng hoạt động. Lời gọi tới nó trả về lỗi nêu tên phiên bản cần chuyển sang. + #### 2026-10-02 {#version-2026-10-02} - ## Trong giai đoạn beta {#beta} + Phiên bản theo ngày đầu tiên: các hình dạng của `v1` tính tới ngày 2 tháng 10 năm 2026. Đang được hỗ trợ; chưa có ngày tắt. - Khi API còn ở bản beta, Wandura vẫn có thể phải thay đổi phá vỡ tương thích bên trong `/v1`. Khi đó: + ## Đi theo link thay vì tự dựng URL {#links} - - Thay đổi được báo trước ít nhất **30 ngày** trước khi có hiệu lực, trong nhật ký thay đổi và qua email cho Admin của mọi tổ chức đang dùng API. - - Bản vá bảo mật khẩn có thể có hiệu lực ngay. Nó được thông báo ngay khi đã chạy. + Response mang sẵn các URL bạn cần tiếp theo, dạng tuyệt đối, trong `links`: + | Endpoint | Link | + |---|---| + | [Lấy catalog được cấp phép](../reference/catalog.md) | `self`, `next` (`null` ở trang cuối hoặc khi không chia trang), `playback`, `config` | + | [Liệt kê creative](../reference/creatives-list.md) | `self`, `next`; và `self` ở từng creative | + | [Liệt kê video mở](../reference/videos-list.md) | `self`, `next` | + | [Lấy cấu hình](../reference/config.md) | mọi endpoint, tài liệu, nguồn changelog | + + Cursor là chuỗi opaque: chép nguyên văn, không bao giờ giải mã hay tự dựng. + + ## Đọc cấu hình của bạn {#config} + + [`GET /api/delivery/v1/config`](../reference/config.md) cho backend của bạn biết, theo key của bạn: các ngưỡng đang áp cho bạn, thiết lập playback và thời hạn vé, giới hạn lô, ngôn ngữ phụ đề, các phiên bản API (đang ghim, mới nhất, còn hỗ trợ) và mọi thông báo ngừng hỗ trợ. Đọc nó lúc khởi động hoặc vài giờ một lần, thay vì hard-code các giá trị này. + + ## Ngừng hỗ trợ và ngày tắt {#deprecations} + + Khi một endpoint hay một phiên bản theo ngày sắp bị gỡ, Wandura thông báo ở bốn chỗ cùng lúc: + + 1. **Header response**, trên mọi response nó trả về: `Deprecation: @<unix seconds>` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)), `Sunset: <HTTP date>` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)), và `Link: <https://docs.wandura.ai/…>; rel="deprecation"`. + 2. Danh sách `deprecations` trong `GET /config`. + 3. Nguồn dữ liệu cho máy đọc `https://docs.wandura.ai/changes.json` (`api_versions`, `deprecations`). + 4. Changelog, và email gửi Admin của mọi tổ chức đang dùng API. + + Một trường đơn lẻ bị ngừng hỗ trợ thì không có header; nó được liệt kê ở ba chỗ còn lại. Ghi các header này vào hệ thống giám sát của bạn ([Observability](../production/observability.md)). Hiện chưa có gì bị ngừng hỗ trợ. + + ## Thời gian hỗ trợ {#support-window} + + Khi một phiên bản lớn mới (ví dụ `/v2`) được phát hành, Wandura công bố trong changelog và qua email cho Admin của bạn, giữ phiên bản trước chạy không đổi trong **12 tháng**, giữ tài liệu của nó trực tuyến dưới dạng phiên bản cũ, rồi mới gỡ: lời gọi tới nó trả về lỗi nêu tên phiên bản cần chuyển sang. + + ## Trong giai đoạn beta {#beta} + + Thay đổi phá vỡ tương thích bên trong `/v1` được báo trước ít nhất **30 ngày** trước khi có hiệu lực, trong changelog và qua email cho Admin của bạn. Bản vá bảo mật khẩn có thể có hiệu lực ngay; nó được thông báo ngay khi đã chạy. + ## Theo dõi thay đổi ở đâu {#follow-changes} - - **Nhật ký thay đổi** — link ở cuối mọi trang. Liệt kê mọi trang đã sửa, theo từng ngày. - - **Lịch sử thay đổi** — mỗi trang ghi lần cập nhật gần nhất và link tới lịch sử riêng, có đúng các dòng đã thêm và bớt. - - **Góp ý** — bấm **Gửi góp ý** ở đầu mọi trang nếu có chỗ chưa rõ hoặc một thay đổi làm bạn bất ngờ. + - **Changelog**: trong menu; mọi trang đã đổi, theo từng ngày. + - **Lịch sử thay đổi**: mỗi trang có link tới lịch sử riêng của nó. + - **`changes.json`**: cho hệ thống giám sát của bạn. + - **Send feedback** ở đầu mỗi trang nếu một thay đổi làm bạn bất ngờ. + + ## Liên quan {#related} + + - [Chuyển phiên bản](../guides/migrating-versions.md) + - [Hành vi chuẩn của API · Phiên bản](../reference/behaviour.md#versioning)
- 02/10/2026 · +1 −1 dòng
Xem thay đổi
⋯ Phiên bản API là một phần của mọi path: `https://www.wandura.ai/api/delivery/v1/…`. Bạn chọn phiên bản lớn qua path bạn gọi; bạn không phải đặt header nào. Trong giai đoạn beta, mọi response từ `/v1` còn mang `Wandura-API-Status: beta`. - **Đang triển khai — phiên bản theo ngày bên trong `/v1`.** Hình dạng response bên trong `/v1` sẽ mang thêm một ngày (ví dụ `2026-10-02`): API key của bạn được ghim vào bản hiện hành lúc tạo key, mọi response nói nó dùng bản nào trong header `Wandura-Version`, và bạn có thể thử bản mới hơn theo từng request bằng cách gửi header đó. Khi đó một thay đổi hình dạng được phát hành thành bản ngày mới, và key của bạn vẫn nhận hình cũ tới ngày tắt của bản đó. Xem [API tiến hoá](api-evolution.md#dated-versions). + **Phiên bản theo ngày bên trong `/v1`.** Hình dạng response bên trong `/v1` mang thêm một ngày (ví dụ `2026-10-02`): API key của bạn được ghim vào bản hiện hành lúc tạo key, mọi response nói nó dùng bản nào trong header `Wandura-Version`, và bạn có thể thử bản mới hơn theo từng request bằng cách gửi header đó. Khi đó một thay đổi hình dạng được phát hành thành bản ngày mới, và key của bạn vẫn nhận hình cũ tới ngày tắt của bản đó. Xem [API tiến hoá](api-evolution.md#dated-versions). ## Thay đổi không phá vỡ tương thích {#additive} ⋯
- 02/10/2026 · +5 −1 dòng
Xem thay đổi
⋯ ## Phiên bản hoạt động thế nào {#how-versions-work} - Phiên bản API là một phần của mọi path: `https://www.wandura.ai/api/delivery/v1/…`. Bạn chọn phiên bản qua path bạn gọi; không có header nào cần đặt. Trong giai đoạn beta, mọi response từ `/v1` còn mang `Wandura-API-Status: beta`. + Phiên bản API là một phần của mọi path: `https://www.wandura.ai/api/delivery/v1/…`. Bạn chọn phiên bản lớn qua path bạn gọi; bạn không phải đặt header nào. Trong giai đoạn beta, mọi response từ `/v1` còn mang `Wandura-API-Status: beta`. + **Đang triển khai — phiên bản theo ngày bên trong `/v1`.** Hình dạng response bên trong `/v1` sẽ mang thêm một ngày (ví dụ `2026-10-02`): API key của bạn được ghim vào bản hiện hành lúc tạo key, mọi response nói nó dùng bản nào trong header `Wandura-Version`, và bạn có thể thử bản mới hơn theo từng request bằng cách gửi header đó. Khi đó một thay đổi hình dạng được phát hành thành bản ngày mới, và key của bạn vẫn nhận hình cũ tới ngày tắt của bản đó. Xem [API tiến hoá](api-evolution.md#dated-versions). + ## Thay đổi không phá vỡ tương thích {#additive} ⋯ - Nâng rate limit. + Luật để tích hợp của bạn không bị ảnh hưởng nằm ở [API tiến hoá](api-evolution.md#tolerant-reader). + ## Thay đổi phá vỡ tương thích {#breaking} ⋯
- 01/10/2026 · Tạo trang