版本管理

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

版本管理架構

Merchant API 採用子 API 層級的版本管理策略。也就是說，每個 API (例如 Merchant API 中的產品) 都會有自己的版本生命週期。

版本格式和呈現方式

  • 穩定版子 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 日淘汰產品子 API 第 1 版，該版本最快會在 2027 年 1 月 15 日停用。這個日期過後，您將無法再使用舊版子 API。

子 API 版本和生命週期狀態

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

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

最佳做法

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