API 版本策略

Shoplazza Admin API 采用版本化管理，以便在引入新功能或破坏性变更时不影响现有应用。本页说明版本如何命名、多久发布一次、去哪里查看可用版本，以及迁移时该做什么。

版本命名

每个 API 请求都必须在 URL 路径中包含版本号。版本号采用 YYYY-MM 格式：

https://{shopdomain}.myshoplaza.com/openapi/{version}/{endpoint}

例如，以下 URL 调用 2025-06 版本：

https://{shopdomain}.myshoplaza.com/openapi/2025-06/articles

发布节奏

Shoplazza 每半年发布一个新的 API 版本。新版本可能新增接口和字段，或变更现有行为。旧版本在下线前会持续可用。

查看可用版本

要查看所有可调用的版本，打开 API 参考，使用页面顶部的版本下拉菜单——它始终反映当前可用的版本。

版本下线（Sunset）

当你调用一个不再支持的版本时，请求将返回 404 状态码。请在版本下线前将应用切换到受支持的版本——在 API 参考 的版本下拉菜单中确认当前可用的版本。

迁移检查清单

将应用迁移到新版本时：

1. 查看 API 更新日志，确认新增、变更或移除的接口和字段。
2. 在测试店铺中针对新版本测试你的集成。
3. 更新请求 URL 中的版本段——例如把 2025-06 改为新版本。
4. 灰度切换，在将全部流量切到新版本前先监控错误。