Phiên bản API

~2 phút đọc

Phiên bản API là một ngày dạng YYYY-MM-DD, chọn bằng header DongTien-Version. Phiên bản hiện hành là 2026-10-19. Khi một thay đổi phá vỡ tương thích ra đời, API phát hành một ngày mới; tích hợp đang chạy vẫn nhận đúng hình dạng dữ liệu cũ cho tới khi bạn chủ động nâng.

Phiên bản nào áp dụng cho một yêu cầu

API chọn theo thứ tự sau và dừng ở quy tắc đầu tiên khớp:

Header DongTien-Version có mặt: dùng đúng giá trị đó. Giá trị không có trong danh sách phát hành nhận 400 unsupported_version, trước mọi xử lý khác.
Không có header: dùng phiên bản đã ghim vào khoá API lúc tạo khoá.
Không có cả hai (phiên đăng nhập, OAuth): dùng phiên bản mới nhất.
Khoá ghim vào một phiên bản đã bị gỡ: phục vụ phiên bản mới nhất để tích hợp không gãy; header phản hồi cho biết phiên bản đã áp dụng.

Mọi phản hồi, kể cả lỗi application/problem+json và 404, trả lại DongTien-Version đã áp dụng. Hãy ghi giá trị này vào log của bạn khi điều tra khác biệt dữ liệu.

GET /v1/transactions HTTP/1.1
Authorization: Bearer dt_test_…
DongTien-Version: 2026-10-19

SDK nhận phiên bản qua tuỳ chọn khi tạo client: version ở TypeScript và Python. Xem SDK TypeScript và SDK Python.

Thay đổi nào cần ngày mới

Không phá vỡ (không cần ngày mới)	Phá vỡ (bắt buộc ngày mới)
Thêm route, trường phản hồi, tham số tuỳ chọn, giá trị enum mới ở phản hồi.	Xoá hoặc đổi tên trường hay route, đổi ý nghĩa hoặc kiểu.
Thêm mã lỗi mới.	Thắt chặt kiểm tra đầu vào, bỏ một giá trị enum.
Sửa lỗi chính tả trong mô tả.	Đổi thứ tự sắp xếp mặc định, đổi quy tắc phân trang.

Vì thêm trường và thêm mã lỗi là không phá vỡ, mã của bạn cần bỏ qua trường lạ và có nhánh mặc định cho code chưa biết.

Ngừng hỗ trợ một phiên bản

Phiên bản cũ có thể bị đánh dấu ngừng. Khi đó mọi phản hồi của phiên bản ấy mang thêm các header Deprecation (RFC 9745), Sunset (RFC 8594) và Link với rel="sunset" trỏ tới tài liệu. Khoảng cách từ ngày đánh dấu ngừng tới ngày gỡ tối thiểu là 6 tháng, và chủ khoá đang dùng phiên bản đó được báo qua email trước hạn.