# Chuyển phiên bản

> **TL;DR** — Key của bạn được ghim vào một phiên bản theo ngày. Khi Wandura phát hành phiên bản mới hơn: đọc những gì đã thay đổi, thử nó theo từng request bằng header `Wandura-Version`, rồi chuyển key (key mới được ghim vào phiên bản mới nhất; key được xoay vòng giữ nguyên phiên bản đã ghim). Một major version mới (`/v2`) có 12 tháng chạy song song.

Hiện có một phiên bản theo ngày, `2026-10-02`, nên chưa có gì để chuyển. Trang này là quy trình cho lúc cần chuyển.

## 1. Biết mình đang ở đâu
```bash
curl -s https://www.wandura.ai/api/delivery/v1/config \
  -H "Authorization: Bearer $WANDURA_API_KEY"
```

`api.pinned_version` là phiên bản của key bạn, `api.latest_version` là phiên bản mới nhất, `api.supported_versions` là các phiên bản bạn được gửi, mỗi phiên bản kèm `deprecated_at` và `sunset_at`. Mọi response cũng cho biết phiên bản đã dùng, trong `Wandura-Version`. Hãy ghi log header đó.

## 2. Đọc những gì đã thay đổi
[Lịch sử phiên bản](https://docs.wandura.ai/vi/v1/developers/concepts/versioning#version-history), changelog, và `https://docs.wandura.ai/changes.json` (`api_versions`) liệt kê từng phiên bản và các thay đổi của nó.

## 3. Thử phiên bản mới theo từng request
Gửi `Wandura-Version: <ngày mới>` trên vài request từ một môi trường test (tốt nhất là tổ chức test của bạn). Header này ghi đè phiên bản đã ghim của key chỉ cho request đó. Giá trị lạ hoặc đã khai tử trả `400` `unsupported_version` kèm các phiên bản bạn dùng được.

## 4. Chuyển key
| Cách | Phiên bản ghim sau đó | Gián đoạn |
|---|---|---|
| **Tạo key mới** với cùng scope, triển khai nó, thu hồi key cũ | Phiên bản **mới nhất** | Không |
| Xoay vòng key cũ | **Không đổi**: xoay vòng giữ nguyên phiên bản đã ghim | Secret đổi ngay lập tức |
| Giữ key cũ và gửi `Wandura-Version` trên mọi request | Phiên bản bạn gửi | Không |

Trước khi đổi key trong tình huống khẩn cấp (key bị lộ), kiểm tra phiên bản của key mới khớp với điều code của bạn mong đợi: key mới ở phiên bản mới nhất.

## 5. Theo dõi deprecation
Một phiên bản hoặc endpoint đã deprecated trả các header `Deprecation`, `Sunset` và `Link` trên mọi response. Hãy cảnh báo khi thấy chúng ([Quan sát hệ thống](https://docs.wandura.ai/vi/v1/developers/production/observability)). Thời gian báo trước: 30 ngày trong giai đoạn beta, 12 tháng sau đó.

## Liên quan
- [Versioning và API tiến hoá](https://docs.wandura.ai/vi/v1/developers/concepts/versioning)