# Phiên bản và API tiến hoá

> **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
| 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`. |

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.

## Đọc response một cách dễ tính
| 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ó. |

## Thay đổi không phá vỡ tương thích
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
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](https://docs.wandura.ai/vi/v1/developers/concepts/versioning#beta).

## Phiên bản theo ngày
- **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](https://docs.wandura.ai/vi/v1/developers/guides/migrating-versions).

### Lịch sử phiên bản
#### 2026-10-02
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.

## Đi theo link thay vì tự dựng URL
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](https://docs.wandura.ai/vi/v1/developers/reference/catalog) | `self`, `next` (`null` ở trang cuối hoặc khi không chia trang), `playback`, `config` |
| [Liệt kê creative](https://docs.wandura.ai/vi/v1/developers/reference/creatives-list) | `self`, `next`; và `self` ở từng creative |
| [Liệt kê video mở](https://docs.wandura.ai/vi/v1/developers/reference/videos-list) | `self`, `next` |
| [Lấy cấu hình](https://docs.wandura.ai/vi/v1/developers/reference/config) | 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
[`GET /api/delivery/v1/config`](https://docs.wandura.ai/vi/v1/developers/reference/config) 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
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](https://docs.wandura.ai/vi/v1/developers/production/observability)). Hiện chưa có gì bị ngừng hỗ trợ.

## Thời gian hỗ trợ
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
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
- **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
- [Chuyển phiên bản](https://docs.wandura.ai/vi/v1/developers/guides/migrating-versions)
- [Hành vi chuẩn của API · Phiên bản](https://docs.wandura.ai/vi/v1/developers/reference/behaviour#versioning)