# 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 バージョンを指定せずに連結アカウントに代わってリクエストを行う場合、Stripe は常にプラットフォームの API バージョンを使用します。連結アカウントの API バージョンに関係なく、プラットフォームの代理リクエストは、常にリクエストの API バージョンに一致するレスポンスを返します。

## 下位互換性のある変更

Stripe は、次の変更に下位互換性があると見なします。

- 新しい API リソースを追加。
- 既存の API メソッドに新しいオプションのリクエストパラメータを追加。
- 既存の API レスポンスに新しいプロパティを追加。
- 既存の API レスポンス内のプロパティの順序を変更。
- オブジェクト ID、エラーメッセージ、その他の人間が解読できる文字列などの opaque 型の文字列の長さまたは形式を変更。
  - これには、固定のプレフィックス (支払い ID に対する `ch_` など) の追加または削除が含まれます。
  - Stripe で生成する、最大 255 文字が含まれることのあるオブジェクト ID をシステムで処理できるようにします。たとえば MySQL を使用している場合は、ID を `VARCHAR(255) COLLATE utf8_bin` 列に格納する必要があります (`COLLATE` 構成を使用すると検索で大文字小文字が区別されます)。
- 新しいイベントタイプを追加。
  - Webhook リスナーが不明なイベントタイプを適切に処理することを確認します。

## API バージョンをアップグレードする

古いバージョンの API を実行している場合は、最新バージョンにアップグレードすることで、新機能や拡張機能を利用できるようになります。

API バージョンをアップグレードすると、次のような影響があります。

- `Stripe-Version` ヘッダなしで実行する API コール (送信できるパラメータ、および返されるオブジェクトの構造)。
- [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment) などの [Stripe.js](https://docs.stripe.com/payments/elements.md) メソッドで受信するオブジェクトの構造。
- 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 の変更ログを参照してください。

### ワークベンチで API バージョンと利用可能な最新のアップグレードを確認する

アカウントの [API version used by recent requests (最近のリクエストで使用された API バージョン)](https://docs.stripe.com/workbench/guides.md#view-api-versions) とワークベンチの[概要](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 バージョンを処理できることを確認したら、ワークベンチを使用してアップグレードを実行します。

1. ワークベンチの[概要](https://dashboard.stripe.com/workbench/overview)タブを開きます。
1. **API バージョン**セクションで**アップグレード可能**をクリックします。これは、新しい API バージョンが利用可能な場合に表示されます。
1. アカウントに割り当てられる API バージョンを確認して、**アップグレード**をクリックします。

これにより、`Stripe-Version` ヘッダーのない API コールによって使用されるバージョンが切り替えられ、お客様の Ｗebhook に送信されるオブジェクトのレンダリングに使用されるバージョンも切り替えられます。

> [API から取得されたイベント](https://docs.stripe.com/api/events.md)内のリソースの形状は、イベントが発生した時点でのアカウントのデフォルトの API バージョンによって定義されます。デフォルトの API バージョンが異なっていたときに作成されたイベントをお客様のコードで取得する場合は、イベントバージョンの違いを考慮する必要があります。

### API バージョンのロールバック

API バージョンをアップグレードしてから 72 時間は、ワークベンチでアップグレード前のバージョンに安全にロールバックできます。

バージョンをロールバックすると、新しいオブジェクト構造で送信されて失敗した Ｗebhook は古い構造で再試行されます。

## 最新情報を入手

Stripe では、Stripe の API や言語ライブラリへの新しい追加事項や変更についてお知らせする Stripe 開発者ダイジェストをお送りしています。最新情報を得るためにぜひご[購読](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)をご覧ください。