Lập phiên bản

Hướng dẫn này giải thích cách Merchant API xử lý việc lập phiên bản, phát hành và vòng đời của các phiên bản khác nhau.

Lược đồ lập phiên bản

Merchant API sử dụng chiến lược lập phiên bản ở cấp độ API phụ. Điều này có nghĩa là mỗi Merchant API (ví dụ: Sản phẩm trong Merchant API) sẽ có vòng đời phiên bản riêng.

Định dạng và cách trình bày phiên bản

• Phiên bản API phụ ổn định: Nếu một API phụ ở phiên bản ổn định thì tất cả các phương thức của API phụ đó đều ở phiên bản ổn định. Phiên bản API phụ ổn định được biểu thị là vX (ví dụ: v1, v2). Đây là các phiên bản chính sẵn sàng cho hoạt động sản xuất.

• Phiên bản API phụ alpha: Nếu một API phụ ở phiên bản alpha thì tất cả các phương thức của API phụ đó đều ở phiên bản alpha. Phiên bản API phụ alpha được biểu thị là vXalpha (ví dụ: v1alpha, v2alpha). Các phiên bản này chứa các tính năng thử nghiệm, truy cập sớm dành cho mục đích kiểm thử và lặp lại nhanh. Phiên bản alpha không đảm bảo độ ổn định, không có thời gian tồn tại xác định và có thể bị thay đổi hoặc ngừng hoạt động với thời gian thông báo là 30 ngày.

Các lần thay đổi phiên bản

• Số gia phiên bản lớn (ví dụ: v1 thành v2): Các số gia này báo hiệu các thay đổi không có khả năng tương thích ngược và có thể gây lỗi, đòi hỏi nhà phát triển phải thực hiện hành động. Chỉ những thay đổi có thể gây lỗi của các API phụ ổn định mới có số phiên bản mới. Ví dụ: v1 thành v2.
• Các thay đổi nhỏ: Các bổ sung hoặc bản sửa lỗi tương thích ngược được trình bày dưới dạng các thay đổi đối với phiên bản lớn hiện có. Những thay đổi như vậy sẽ được trình bày chi tiết trong ghi chú phát hành cho phiên bản lớn đó. Các bổ sung không gây lỗi cho API phụ sẽ được phát hành cho kênh alpha của phiên bản ổn định mới nhất hoặc trực tiếp cho phiên bản ổn định mới nhất.

Chính sách ngừng hoạt động

Chúng tôi định kỳ ngừng hoạt động các phiên bản API phụ cũ của Merchant. Chúng tôi cam kết có khoảng thời gian ngừng sử dụng là 12 tháng đối với các phiên bản chính ổn định (vX), bắt đầu từ thông báo ngừng sử dụng chính thức.

Ví dụ: nếu chúng tôi ngừng sử dụng phiên bản v1 của API phụ Sản phẩm vào ngày 15 tháng 1 năm 2026, thì phiên bản này sẽ ngừng hoạt động không sớm hơn ngày 15 tháng 1 năm 2027. Sau ngày này, bạn sẽ không còn sử dụng được phiên bản cũ của API phụ.

Trạng thái phiên bản và vòng đời của API phụ

Bảng sau đây liệt kê các phiên bản mới nhất của từng API phụ của Merchant API:

Các phương pháp hay nhất

• Thường xuyên kiểm tra ghi chú phát hành và thông tin cập nhật mới nhất để biết các phiên bản mới, bản cập nhật chính, cải tiến và thông báo về việc ra mắt và ngừng sử dụng API phụ.
• Nếu một API phụ có từ hai phiên bản ổn định trở lên, bạn nên luôn sử dụng phiên bản mới nhất.
• Thiết kế ứng dụng để xử lý một cách thích hợp nhiều lỗi API phụ, bao gồm cả vấn đề về mạng, giới hạn tốc độ và mã lỗi hoặc thông báo lỗi mới có thể được giới thiệu trong các phiên bản API phụ mới hơn.
• Đừng đợi đến khi một phiên bản API phụ sắp ngừng hoạt động mới bắt đầu lên kế hoạch nâng cấp. Hãy bắt đầu đánh giá và kiểm thử các phiên bản mới ngay khi chúng được cung cấp.
• Nếu bạn có yêu cầu về tính năng hoặc lo ngại về lộ trình API phụ, hãy liên hệ với chúng tôi để đặt câu hỏi hoặc gửi ý kiến phản hồi. Để biết thông tin về cách liên hệ với nhóm Merchant API để được hỗ trợ kỹ thuật, hãy xem bài viết Nhận trợ giúp về Merchant API.