本指南介绍了 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 | 版本 | 状态 |
|---|---|---|
| Accounts | v1 v1alpha v1beta |
有效 有效 已于 2026 年 2 月 28 日停用 |
| Conversions | v1 v1beta |
有效 已于 2026 年 2 月 28 日停用 |
| Data sources | v1 v1beta |
有效 已于 2026 年 2 月 28 日停用 |
| Inventories | v1 v1beta |
有效 已于 2026 年 2 月 28 日停用 |
| Issue resolution | v1 v1beta |
有效 已于 2026 年 2 月 28 日停用 |
| Local feeds partnership | v1 v1beta |
有效 已于 2026 年 2 月 28 日停用 |
| Notifications | v1 v1beta |
有效 已于 2026 年 2 月 28 日停用 |
| Order tracking | v1 v1beta |
有效 已于 2026 年 2 月 28 日停用 |
| Products | v1 v1beta |
有效 已于 2026 年 2 月 28 日停用 |
| Product Studio | v1alpha | 有效 |
| Promotions | v1 v1beta |
有效 已于 2026 年 2 月 28 日停用 |
| Quota | v1 v1beta |
有效 已于 2026 年 2 月 28 日停用 |
| Reports | v1 v1beta |
有效 已于 2026 年 2 月 28 日停用 |
| Reviews | v1alpha v1beta |
有效 已于 2026 年 2 月 28 日停用 |
最佳实践
- 定期查看版本说明和最新更新 ，了解新版本、重大更新、改进以及有关 sub-API 发布和弃用的公告。
- 如果 sub-API 有两个或更多稳定版，我们建议您始终使用最新版本。
- 将应用设计为妥善处理各种 sub-API 错误，包括网络问题、速率限制以及可能随较新 sub-API 版本引入的新错误代码或消息。
- 不要等到 sub-API 版本即将停用时才开始规划升级。新版本一经推出，便立即开始评估和测试。
- 如果您有功能请求或对 sub-API 路线图有任何疑问，请随时与我们联系 ，提出问题或反馈。如需了解如何与 Merchant API 团队联系以获取技术 支持，请参阅获取 Merchant API 方面的帮助。