本指南說明 Merchant API 如何處理版本管理、版本發布和不同版本的生命週期。
版本管理架構
Merchant API 會在子 API 層級採用版本管理策略。也就是說，Merchant API 中的個別元件或服務都會有各自的版本生命週期。
版本格式和呈現方式
穩定的子 API 版本：如果子 API 為穩定版，則其所有方法皆為穩定版。穩定的子 API 版本會以 vX 表示 (例如 v1、v2)。這些是可正式發布的重大版本。
Alpha 子 API 版本：如果子 API 為 Alpha 版本，則其所有方法皆為 Alpha 版本。Alpha 子 API 版本會以 vXalpha 表示 (例如 v1alpha、v2alpha)。這些是搶先體驗版，屬於實驗性質，旨在進行測試和快速疊代。Alpha 版本不提供穩定性保證，且不保證壽命。您可以在發出 30 天的通知後，變更或停止 Alpha 版本。
版本變更
主要版本遞增 (例如從 v1 到 v2)：這類版本號碼代表不相容的回溯性變更和破壞性變更，需要開發人員採取行動。只有穩定子 API 的重大變更才會採用新版本號碼。例如從 v1 改為 v2。
次要變更：向後相容的新增項目或修正項目會顯示為現有主要版本的變更項目。這些變更會在該主要版本的發布說明中詳細說明。對子 API 的非破壞性新增項目會發布至最新穩定版本的 Alpha 管道，或直接發布至最新穩定版本。
日落
我們會定期淘汰舊版 Merchant 子 API。我們承諾，自官方停用公告起算，穩定版主要版本 (vX) 的停用時間為 12 個月。
舉例來說，如果我們在 2026 年 1 月 15 日淘汰 Products 子 API 的 1.0 版，則該 API 最快會在 2027 年 1 月 15 日停用。屆時舊版子 API 將無法再使用。
子 API 版本和生命週期狀態
下表列出 Merchant API 各個子 API 的最新版本：
| 子 API | Alpha 版本 | Beta 版 | 狀態 |
|---|---|---|---|
| 帳戶 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| 產品 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| 產品輸入內容 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| 店面商品目錄 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| 區域商品目錄資料 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| 資料來源 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| 促銷優惠 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| 報表 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| 轉換 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| 通知 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| 評論 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| 運送設定 | 不適用 | 第 1 版 Beta | 已啟用 v1 Beta 版 |
| Product Studio | 第 1 個 Alpha 版 | 不適用 | 已啟用 v1 Alpha 版 |
最佳做法
- 請定期查看版本資訊和最新更新，瞭解新版本、重大更新、改善項目，以及有關子 API 推出和淘汰的公告。
- 如果子 API 有 2 個以上的穩定版本，建議您一律使用最新版本。
- 設計應用程式時，請妥善處理各種子 API 錯誤，包括網路問題、速率限制，以及新版子 API 可能會引入的新錯誤代碼或訊息。
- 請勿等到子 API 版本即將淘汰，才開始規劃升級作業。新版本推出後，立即開始評估及測試。
- 如果您對子 API 路線圖有功能要求或疑慮，請向我們提出問題或意見回饋。如要瞭解如何與 Merchant API 團隊聯絡，請參閱「取得 Merchant API 相關協助」。