# API 升级

跟踪 Stripe API 更新与升级。

> 可在私人预览中浏览 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)。

您的 API 版本控制着您看到的 API 和 Webhook 的行为（例如，您可以在请求中包含哪些参数、在响应中看到哪些属性等）。在您首次创建 API 请求时设置您的版本。每个主要版本（如 [Acacia](https://docs.stripe.com/changelog/acacia.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

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

### 执行升级

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

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

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

> [从 API 检索到的](https://docs.stripe.com/api/events.md) 事件中的资源形状由事件发生时您账户的默认 API 版本定义。如果您的代码检索在不同于默认 API 版本时创建的事件，则必须考虑事件版本中的一切差异。

### 回滚您的 API 版本

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

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

## 时刻掌握

我们会通过 Stripe 开发人员简报发送 API 更新、新增功能及各语言库的变更信息。请务必[订阅](https://go.stripe.global/dev-digest)以便及时掌握相关动态。

## API 版本

> 该部分不再更新。要了解有关 Stripe API 更新的信息，请访问新的[更改日志](https://docs.stripe.com/changelog.md)。

以下列出了 Stripe API 的所有[重大变更](https://docs.stripe.com/upgrades.md#breaking-change)。每个日期对应一个 Stripe API 的新版本。如需查看所有 API 新增功能和更新，请参阅 [API 更新日志](https://docs.stripe.com/changelog.md)。如需查看新产品发布，请参阅[产品更新日志](https://stripe.com/blog/changelog)。