Hướng dẫn này giải thích cách Merchant API xử lý việc tạo 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 tạo phiên bản ở cấp độ API phụ. Điều này có nghĩa là mỗi Merchant API, chẳng hạn như Products 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ụ đang ở phiên bản ổn định thì tất cả các phương thức của API đó đều ở phiên bản ổn định. Phiên bản API phụ ổn định được biểu thị dưới dạng vX (ví dụ: v1, v2). Đây là các phiên bản chính đã sẵn sàng cho môi trường thực tế.
Phiên bản API phụ alpha: Nếu một API phụ ở giai đoạn alpha, thì tất cả các phương thức của API đó đều ở giai đoạn alpha. Phiên bản API phụ alpha được biểu thị dưới dạng vXalpha (ví dụ: v1alpha, v2alpha). Các bản phát hành này chứa các tính năng thử nghiệm, tiếp cận sớm nhằm mục đích thử nghiệm và lặp lại nhanh chóng. Các phiên bản Alpha không đảm bảo tính ổn định, không có thời hạn sử dụng xác định và có thể 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
- Tăng phiên bản chính (ví dụ: phiên bản 1 lên phiên bản 2): Những thay đổi này báo hiệu những 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 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ụ: phiên bản 1 lên phiên bản 2.
- Thay đổi nhỏ: Các bản sửa lỗi hoặc bổ sung có khả năng 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 đó sẽ được trình bày chi tiết trong ghi chú phát hành của phiên bản lớn đó. Các nội dung bổ sung không gây lỗi cho một 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 cung cấp các phiên bản Merchant API phụ cũ. Chúng tôi cam kết áp dụng thời gian không dùng nữa 12 tháng cho các phiên bản lớn ổn định (vX), bắt đầu từ thông báo không dùng nữa chính thức.
Ví dụ: nếu chúng tôi ngừng sử dụng phiên bản 1 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 sớm nhất vào ngày 15 tháng 1 năm 2027. Sau ngày này, bạn sẽ không thể sử dụng phiên bản cũ của API phụ nữa.
Phiên bản API phụ và trạng thái vòng đời
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:
| API phụ | Phiên bản | Trạng thái |
|---|---|---|
| Tài khoản | v1 v1alpha |
Đang hoạt động Đang hoạt động |
| Lượt chuyển đổi | v1 | Đang hoạt động |
| Nguồn dữ liệu | v1 | Đang hoạt động |
| Khoảng không quảng cáo | v1 | Đang hoạt động |
| Giải quyết vấn đề | v1 | Đang hoạt động |
| Chương trình đối tác nguồn cấp dữ liệu địa phương | v1 | Đang hoạt động |
| Thông báo | v1 | Đang hoạt động |
| Thông tin theo dõi đơn đặt hàng | v1 | Đang hoạt động |
| Sản phẩm | v1 | Đang hoạt động |
| Product Studio | v1alpha | Đang hoạt động |
| Khuyến mãi | v1 | Đang hoạt động |
| Hạn mức | v1 | Đang hoạt động |
| Báo cáo | v1 | Đang hoạt động |
| Bài đánh giá | v1alpha | Đang hoạt động |
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 lớn, điểm cải tiến và thông báo về việc ra mắt cũng như 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 của bạn để xử lý linh hoạt 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. Bắt đầu đánh giá và thử nghiệm các phiên bản mới ngay khi có.
- Nếu bạn có yêu cầu về tính năng hoặc thắc mắc về lộ trình của một 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 phụ trách API Merchant để được hỗ trợ kỹ thuật, hãy xem bài viết Yêu cầu trợ giúp về Merchant API.