---
title: "API 版本管理说明"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/api-versioning-guide'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/api-versioning-guide.md'
---
# API 版本说明

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

> **提示**
>
> 为及时获取 API 版本更新动态，需确保你在 [合作伙伴后台](https://developer.myshopline.com/home/index) 的联系方式准确有效，并留意站内信与邮件通知。同时，你也可以关注开发者文档的 [版本变更日志](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/api-release-notes/api-release-notes.md)。

------

## 版本化和非版本化 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 日 |