API 版本说明

为了适应不断发展的业务需求，SHOPLINE 会定期进行 API 版本迭代。这不仅确保你能构建能力丰富且贴近商家实际使用需求的应用，也为 API 的功能升级与废弃提供了清晰可预期的过渡机制。

提示

为及时获取 API 版本更新动态，需确保你在 合作伙伴后台 的联系方式准确有效，并留意站内信与邮件通知。同时，你也可以关注开发者文档的 版本变更日志。

版本化和非版本化 API​

根据稳定性和更新策略的不同，SHOPLINE API 分为版本化和非版本化两种类型。

版本化 API​

版本化 API 具有明确的生命周期和可预期的发版节奏。适用于以下范围：

  • REST Admin API
  • GraphQL Admin API
  • Storefront API
  • Webhook

调用指定 API 版本

在调用版本化 API 时，需要在请求 URL 中指定 API 版本：

  • REST Admin API 路径：/admin/openapi/{version}/{endpoint}.json
  • GraphQL Admin API 路径：/admin/graph/{version}/graphql.json
  • Storefront API 路径：/storefront/graph/{version}/graphql.json

以下示例展示了 v20260901 版本的 API 请求路径：

  • REST Admin API（查询订单）：/admin/openapi/v20260901/orders.json
  • GraphQL Admin API：/admin/graph/v20260901/graphql.json
  • Storefront API：/storefront/graph/v20260901/graphql.json

如果需要切换 API 版本，直接替换请求 URL 中的版本号即可。

提示
  • 与 REST Admin API 通过不同路径（如 /orders.json）区分资源不同，GraphQL Admin API 和 Storefront API 均采用单一端点设计，统一通过 /graphql.json 入口访问。具体的资源请求需在请求体的 GraphQL 查询语句中指定。
  • Webhook 属于事件推送机制，无需主动调用请求。其 API 版本通常在创建 Webhook 订阅时指定。

非版本化 API​

非版本化 API 无固定版本号，可能随时发生变更。适用于以下范围：

  • Ajax API
  • Sline

版本发布类型​

一般情况下，SHOPLINE API 版本会以 3 个月一次的频率进行迭代升级。SHOPLINE 发布的版本包括 3 种类型：稳定版本、候选版本和不稳定版本。

稳定版本​

  • 你可以安全调用稳定版本的 API，无需担心发生不兼容变更。
  • 通常一个版本转为稳定版本后会持续服务 12 个月。
  • 连续两个稳定版本之间会有 9 个月的重叠服务期。这意味着，当新的稳定版本引入了影响应用的变更时，你可以有 9 个月的时间进行迭代迁移。

候选版本​

  • 候选版本可视为下一稳定版本的预览版，包含计划在下一稳定版本中发布的变更。
  • 通常，当上一版本转为稳定版本时，下一版本即成为候选版本。例如，当 v20260901 变为稳定版本时，v20261201 将作为候选版本发布。
  • 候选版本会包含所有向后兼容或向后不兼容的变更，你可以据此尽早进行应用适配，但不建议在生产环境中直接使用。

不稳定版本​

  • 不稳定版本包含仍在开发和迭代中的接口和更新，可能会不定期发生向后兼容或向后不兼容的变更。
  • 一个特性被添加到不稳定版本后，仍然有可能被删除。
  • 你可以利用不稳定版本尽早测试新的接口和功能，但不建议在生产环境中使用它们。

废弃说明​

如果 SHOPLINE API 的部分功能不再适用、存在安全风险或已过时，SHOPLINE 可能会将其废弃。相关接口或资源的停用通常会经历以下三个阶段：

  1. 标记废弃：特定的接口或资源会首先在当前版本中被标记为已废弃。此时功能仍可正常使用，但强烈建议尽快迁移。
  2. 正式移除：随后，该接口或资源将在特定新版本中被正式移除。此时若通过该新版本请求已移除的接口或资源，系统将返回 HTTP 405 错误；但在尚未过期的历史版本中，该功能依然可用。
  3. 彻底停用：根据 SHOPLINE API 的版本管理规划，当包含该接口或资源的最后一个旧版本被正式关闭时，该功能才会彻底不可用。

发布时间表​

SHOPLINE API 各版本的生命周期节点如下。

提示
  • 每个 API 版本会在初始发布日期作为不稳定版本推出，并在后续按计划逐步过渡为候选版本和稳定版本。
  • 表中所示废弃日期为该版本预计最早废弃的时间点。SHOPLINE 可能会根据实际情况延长旧版本的生命周期；版本在真正废弃前，将提前发送通知。
版本号版本状态初始发布日期稳定版本日期废弃日期
v20270301不稳定版本2026 年 08 月 14 日2027 年 03 月 01 日2028 年 03 月 01 日
v20261201候选版本2026 年 06 月 25 日2026 年 12 月 01 日2027 年 12 月 01 日
v20260901稳定版本2026 年 04 月 02 日2026 年 08 月 14 日2027 年 09 月 01 日
v20260601稳定版本2025 年 12 月 25 日2026 年 06 月 01 日2027 年 06 月 01 日
v20260301稳定版本2025 年 09 月 04 日2026 年 03 月 01 日2027 年 03 月 01 日
v20251201稳定版本2025 年 06 月 19 日2025 年 12 月 01 日2026 年 12 月 01 日
v20250601稳定版本2025 年 01 月 02 日2025 年 06 月 01 日2026 年 06 月 01 日
v20250301稳定版本2024 年 09 月 01 日2025 年 03 月 01 日2026 年 03 月 01 日
v20241201已废弃2024 年 06 月 12 日2024 年 12 月 01 日2025 年 12 月 01 日
v20240601已废弃2024 年 01 月 10 日2024 年 06 月 01 日2025 年 06 月 01 日
v20240301已废弃2023 年 11 月 08 日2024 年 03 月 01 日2025 年 03 月 01 日
v20231201已废弃2023 年 07 月 25 日2023 年 12 月 01 日2024 年 12 月 01 日
v20230901已废弃2023 年 05 月 01 日2023 年 09 月 01 日2024 年 09 月 01 日
v20230301已废弃2023 年 02 月 23 日2023 年 06 月 01 日2024 年 06 月 01 日
v20220901已废弃2022 年 09 月 01 日2023 年 04 月 01 日2024 年 03 月 01 日
v20220601已废弃2022 年 06 月 01 日2023 年 04 月 01 日2023 年 12 月 01 日
v20210901已废弃2021 年 09 月 01 日2023 年 04 月 01 日2023 年 09 月 01 日
这篇文章对你有帮助吗？
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
条款协议
隐私
条款
开发者协议
LinkedInEmail
LinkedInEmail
© Copyright 2013-2026 SHOPLINE Limited.