本指南說明 Merchant API 如何處理版本管理、發布作業，以及不同版本的生命週期。
版本管理架構
Merchant API 會在子 API 層級採用版本管理策略。也就是說，每個 Merchant 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 v1alpha 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 相關協助」。