本指南介绍了 Merchant API 如何处理版本控制、发布及其不同版本的生命周期。
版本控制方案
Merchant API 在 sub-API 级别采用版本控制策略。这意味着每个 Merchant API（例如 Merchant API 中的 Products）都有自己的版本生命周期。
版本控制格式和呈现方式
稳定的 sub-API 版本： 如果 sub-API 处于稳定版本，则其所有方法都处于稳定版本。稳定的 sub-API 版本表示为 vX（例如 v1、v2）。这些是可用于生产用途的主要版本。
Alpha 版 sub-API 版本： 如果 sub-API 处于 Alpha 版，则其所有方法都处于 Alpha 版。Alpha 版 sub-API 版本表示为 vXalpha （例如 v1alpha、v2alpha ）。它们包含实验性抢先体验功能，旨在用于测试和快速迭代。Alpha 版不提供稳定性保证，没有确定的使用期限，并且可以在提前 30 天通知的情况下进行更改或停用。
版本更改
- 主要版本递增 （例如 v1 到 v2）：这些表示需要开发者采取行动的向后不兼容的破坏性更改。只有稳定 sub-API 的重大更改才会有新的版本号。例如，v1 到 v2。
- 次要更改： 后向兼容的添加或修复将作为对现有主要版本的更改呈现。此类更改将在该主要版本的版本说明中详细说明。对 sub-API 的非重大添加将发布到最新稳定版本的 Alpha 版渠道，或直接发布到最新稳定版本。
弃用政策
我们会定期弃用较旧的 Merchant sub-API 版本。我们承诺，从正式弃用公告发布之日起，稳定主要版本 (vX) 的弃用窗口期为 12 个月。
例如，如果我们于 2026 年 1 月 15 日弃用 Products sub-API 的 v1，则该版本最早将于 2027 年 1 月 15 日停用。在此日期之后，将无法再使用该 sub-API 的早期版本。
Sub-API 版本和生命周期状态
下表列出了 Merchant API 的每个 sub-API 的最新版本：
| Sub-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 日停用 |
| 本地 Feed 合作伙伴关系 | 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 日停用 |
最佳实践
- 定期查看版本说明和最新更新 ，了解新版本、重大更新、改进以及有关 sub-API 发布和弃用的公告。
- 如果 sub-API 有两个或多个稳定版本，我们建议您始终使用最新版本。
- 将应用设计为妥善处理各种 sub-API 错误，包括网络问题、速率限制以及可能随较新 sub-API 版本引入的新错误代码或消息。
- 不要等到 sub-API 版本即将停用时才开始规划升级。新版本一经推出，就立即开始评估和测试。
- 如果您有功能请求或对 sub-API 路线图有任何疑问，请随时与我们联系并提供问题或反馈。如需了解如何与 Merchant API 团队联系以获取技术 支持，请参阅获取 Merchant API 方面的帮助。