版本管理

本指南說明 Merchant API 如何處理版本管理、版本發布,以及不同版本的生命週期。

版本管理架構

Merchant API 在子 API 層級採用版本管理策略。這表示每個 Merchant API (例如 Merchant API 中的 Products) 都有自己的版本生命週期。

版本管理格式和呈現方式

  • 穩定版子 API:如果子 API 是穩定版,則其所有方法都是穩定版。穩定的子 API 版本會以 vX 表示 (例如 v1、v2)。這些是可用於正式環境的主要版本。

  • Alpha 子 API 版本:如果子 API 處於 Alpha 版,則其所有方法都處於 Alpha 版。Alpha 子 API 版本的表示方式為 vXalpha (例如 v1alpha、v2alpha)。其中包含實驗性、搶先體驗功能,旨在進行測試和快速疊代。Alpha 版不保證穩定性,沒有明確的使用期限,且可能在 30 天通知期後變更或停用。

版本變更

  • 主要版本遞增 (例如從 v1 升級至 v2):這代表回溯不相容和破壞性變更,需要開發人員採取行動。只有穩定子 API 的破壞性變更,才會獲得新的版本編號。例如從 v1 升級至 v2。
  • 次要變更:回溯相容的新增或修正項目,會以現有主要版本的變更形式呈現。這類異動會詳列在該主要版本的版本資訊中。子 API 的非破壞性新增項目會發布至最新穩定版的 Alpha 版,或直接發布至最新穩定版。

停用政策

我們會定期停用舊版 Merchant 子 API。我們承諾,從正式宣布淘汰穩定主要版本 (vX) 起,會有 12 個月的淘汰緩衝期。

舉例來說,如果我們在 2026 年 1 月 15 日淘汰 Products 子 API 的第 1 版,則該版本最快會在 2027 年 1 月 15 日停用。此日期之後,就無法再使用舊版子 API。

子 API 版本和生命週期狀態

下表列出 Merchant API 各子 API 的最新版本:

子 API 版本 狀態
帳戶 v1
v1alpha
有效
有效
轉換次數 v1 使用中
資料來源 v1 使用中
廣告空間 v1 使用中
解決問題 v1 使用中
店面動態饋給合作夥伴 v1 使用中
通知 v1 使用中
訂單追蹤 v1 使用中
產品 v1 使用中
Product Studio v1alpha 使用中
促銷活動 v1 使用中
配額 v1 使用中
報告 v1 使用中
評論 v1alpha 使用中

最佳做法

  • 請定期查看版本資訊和最新消息,瞭解新版本、重大更新、改善項目,以及子 API 推出和淘汰的公告。
  • 如果子 API 有兩個以上的穩定版本,建議一律使用最新版本。
  • 設計應用程式時,請妥善處理各種子 API 錯誤,包括網路問題、頻率限制,以及新版子 API 可能導入的新錯誤代碼或訊息。
  • 請勿等到子 API 版本即將停用時,才開始規劃升級。新版本推出後,請立即開始評估及測試。
  • 如要提出功能要求,或對子 API 藍圖有疑慮,請與我們聯絡,提出問題或意見回饋。如要瞭解如何與 Merchant API 團隊聯絡,取得技術支援,請參閱「取得 Merchant API 相關協助」。