本指南介绍了 Merchant API 如何处理版本控制、发布及其不同版本的生命周期。
版本控制方案
Merchant API 在子 API 级别采用版本控制策略。这意味着，每个 API（例如 Merchant API 中的 Products）都将有自己的版本生命周期。
版本控制格式和演示
稳定的子 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 的 v1，则最早将于 2027 年 1 月 15 日停用该 API。在此日期之后，将无法再使用该子 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 日停用 |
| 本地 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 日停用 |
最佳做法
- 请定期查看版本说明和最新更新，了解新版本、重大更新、改进以及有关子 API 启动和弃用的公告。
- 如果某个子 API 有两个或更多稳定版本，我们建议您始终使用最新版本。
- 设计应用时，应使其能够妥善处理各种子 API 错误，包括网络问题、速率限制以及可能随较新的子 API 版本引入的新错误代码或消息。
- 不要等到子 API 版本即将停用时才开始规划升级。在新版本发布后立即开始评估和测试。
- 如果您有功能请求或对子 API 路线图有疑虑，请与我们联系，提出问题或提供反馈。如需了解如何联系 Merchant API 团队以获取技术支持，请参阅获取 Merchant API 方面的帮助。