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