# API 升级

了解如何管理 API 版本以及处理主要版本中的重大变更。

查看[开发人员更新日志](https://docs.stripe.com/changelog.md)，获取 Stripe API 变更的完整记录。

API 版本控制着您看到的 API 和 Webhook 行为（例如，您可以在请求中添加哪些参数、在响应中看到哪些属性等）。在您首次发出 API 请求时即会设置版本。每个主要版本（例如 [Basil](https://docs.stripe.com/changelog/basil.md)）包含与先前版本不向后兼容的更改。升级到新的主要版本可能需要更新现有代码。每个月度版本仅包含向后兼容的更改，并使用与上一个主要版本相同的名称。您可以安全地升级到新的月度版本，而不会破坏任何现有代码。如需升级您的 API 版本，请按照[这些步骤](https://docs.stripe.com/upgrades.md#how-can-i-upgrade-my-api)操作。

当 [Connect](https://stripe.com/connect) 平台在未指定 API 版本的情况下代 Connect 子账户发出请求时，Stripe 始终使用平台的 API 版本。无论 Connect 子账户的 API 版本如何，平台代其发出的请求始终返回与请求的 API 版本匹配的响应。

## 向后兼容性更改

Stripe 将以下更改视为向后兼容的：

- 添加新的 API 资源。
- 向当前 API 方法中添加可选的请求参数。
- 向当前 API 响应中添加新的属性。
- 更改当前 API 响应中的属性顺序。
- 更改不透明字符串的长度或格式，例如对象 ID、错误消息及其他人类可读的字串。
  - 这包括添加或删除固定前缀（例如，收款 ID 上的 `ch_`）。
  - 确保您的集成能够处理 Stripe 生成的对象 ID，它最多可以包含 255 个字符。假如您使用的是 MySQL，则在 `VARCHAR(255) COLLATE utf8_bin` 栏中存储 ID（`COLLATE` 配置可确保能够进行区分大小写的查询）。
- 添加新事件类型。
  - 确保您的 Webhook 侦听器能够轻松处理不熟悉的事件类型。

## 升级您的 API 版本

如果您运行的是旧版 API，请升级到最新版本以利用新功能和增强功能。

升级您的 API 版本将影响：

- 您在不使用 `Stripe-Version` 头的情况下进行的 API 调用：您能够发送的参数以及返回的对象的结构。
- 通过 [Stripe.js](https://docs.stripe.com/payments/elements.md) 方法收到的对象的结构，例如 [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment)。
- 发送到您的 Webhook 端点（Account 和 [Connect](https://docs.stripe.com/connect/webhooks.md)）的对象的结构。但是，如果端点设置了显式版本，则始终使用该版本。
- Stripe 执行的自动 Billing 操作（例如，为新的订阅期生成*账单* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice)）使用您账户的默认 API 版本。请参阅 API 更改日志，详细了解默认 API 版本对这些操作的影响。

### 在 Workbench 查看您的 API 版本和最新可用升级

查看您账户上的[近期请求使用的 API 版本](https://docs.stripe.com/workbench/guides.md#view-api-versions)以及 Workbench 的[概览](https://dashboard.stripe.com/workbench/overview)选项卡部分中的最新可用升级。

执行 API 升级时，一定要在您的代码中指定要集成的 API 版本，而不是依赖于您账户的默认 API 版本。要为 API 调用测试较新的版本，应设置 `Stripe-Version` 头（真实或测试环境）。了解如何在我们的[服务器端 SDK](https://docs.stripe.com/sdks.md#server-side-libraries) 中管理版本。

### 升级并测试您的 Webhook

> 可在私人预览中浏览 API v1 资源[轻量级事件](https://docs.stripe.com/event-destinations.md#thin-events)。您可以使用轻量级事件简化集成升级，无需更改 Webhook 配置。以前，轻量级事件仅支持 API v2 资源。[了解更多信息并申请访问权限](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog)。

阅读我们的指南，[了解如何处理 Webhook 版本控制](https://docs.stripe.com/webhooks/versioning.md)。

### 执行升级

如果您确定您的代码能够处理最新 API 版本，请用 Workbench 执行升级：

1. 打开 Workbench 中的[概览](https://dashboard.stripe.com/workbench/overview)选项卡。
2. 在 **API 版本**部分，点击**有可升级版本**（当有新的 API 版本时会显示）。
3. 检查将分配到您的账户的 API 版本，然后点击**升级**。

这将切换没有 `Stripe-Version` 头的 API 调用所使用的版本，也将切换用于渲染发送到您的 Webhook 的对象的版本。

> [从 API 获取的事件](https://docs.stripe.com/api/events.md)的资源，取决于事件发生时您账户的默认 API 版本。如果您的代码检索到的是在您的默认 API 版本与当前不同时创建的事件，则必须考虑事件版本差异带来的影响。

### 回滚您的 API 版本

在您更新您的 API 版本 72 小时后，即可安全地在 Workbench 中回滚到正在升级的版本。

回滚后，以新对象结构发送并且失败的 Webhook 将会以旧机构重试。

## 时刻掌握

[开发人员更新日志](https://docs.stripe.com/changelog.md): Stripe API 变更的完整记录

[Stripe 路线图](https://stripe.com/roadmap): 预览即将发布的 Stripe 产品