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