# API v2 の概要 v2 名前空間の API の動作について説明します。 Stripe API は異なるエンドポイントが含まれる 2 つの名前空間を提供しています。 - **API v1:** `/v1` 名前空間には、現在既存の Stripe API の大部分が含まれています。 - **API v2:** `/v2` 名前空間には、`/v2` デザインパターンを使用するエンドポイントが含まれます。 ## v1 と v2 の名前空間の主な違い | | API v1 | API v2 | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **API にデータを送信する** | リクエストではフォームのエンコード方式 (`application/x-www-form-urlencoded`) が使用され、レスポンスでは JSON のエンコード方式 (`application/json`) が使用されます。 | リクエストとレスポンスでは JSON のエンコード方式 (`application/json`) が使用されます。 | | **導入をテストする** | `/v1` 規約の API は、隔離された環境であるサンドボックスを使用して検証できます。 | `/v2` 名前空間の API は、隔離された環境であるサンドボックスを使用して検証できます。 **詳細を読む:** [サンドボックス](https://docs.stripe.com/sandboxes.md) | | **べき等リクエストを送信する** | `Idempotency-Key` ヘッダーに一意の ID を指定すると、API は、すでにリクエストを処理している場合は、以前に保存されたリクエストを返します。 | `Idempotency-Key` ヘッダーに一意の ID を指定すると、API は副作用 (API コールの結果として発生する外部の変更または観測可能な動作) を発生させずに失敗したリクエストを再試行します。 **詳細を読む:** [べき等](https://docs.stripe.com/api-v2-overview.md#idempotency) | | **Stripe からイベントを受信する** | `/v1` 名前空間の API から発行されるほとんどのイベントには、ペイロードに API オブジェクトのスナップショットが含まれます。`/v1` 名前空間の一部の API は、最小限のバージョン管理されていないプッシュペイロードを含む thin イベントを生成します。 | `/v2` 名前空間の API から発行されるイベントは [thin イベント](https://docs.stripe.com/event-destinations.md#events-overview) です。 **詳細を読む:** [イベントの送信先](https://docs.stripe.com/event-destinations.md) | | **リストをページ分割する** | List API リクエストの先頭のエレメントとしてオブジェクトの ID を指定します。API レスポンスの `starting_after`、`ending_before`、`has_more` のプロパティを使用して、リストをページ分割します。 | List API リクエストに `page` トークンを指定します。API レスポンスの `previous_page_url` プロパティと `next_page_url` プロパティを使用して、リストをページ分割します。 **詳細を読む:** [リストのページ分割](https://docs.stripe.com/api-v2-overview.md#list-pagination) | | **リストの一貫性の保証** | 上位のリストはすぐに一貫性があります (表示されるまでの待ち時間は長くなります)。一部のサブリストは最終的に一貫性があります。 | リストはデフォルトで最終的に一貫性があり、低遅延です。 | | **拡張を使用して追加のデータを取得する** | `expand` パラメーターを使用して、関連する API オブジェクトの ID を拡張された子オブジェクトに置き換えます。 **詳細を読む**: [レスポンスの拡張](https://docs.stripe.com/expand.md) | `expand` パラメーターはサポートされていません。この名前空間の一部の API は、[include parameter](https://docs.stripe.com/api-includable-response-values.md) を使用してレスポンスに追加のフィールドを提供する場合があります。 | | **メタデータを管理する** | 値を空の文字列に設定して、キーと値のペアを削除します。 | 値を `null` に設定して、キーと値のペアを削除します。 | ## API v2 をサポートする SDK すべての[サーバー側 SDK](https://docs.stripe.com/sdks.md#server-side-libraries) は、`/v2` 名前空間の API に対応しています。 ### Stripe CLI で API v2 を使用する `stripe trigger` と `stripe listen` を使用して、実装のイベント処理をテストします。 Stripe CLI を使用して `/v2` 名前空間の API にアクセスするには、`stripe v2` コマンドを使用します。たとえば、すべての [v2 Accounts](https://docs.stripe.com/api/v2/accounts.md) を一覧表示するには、`stripe v2 core accounts list` を使用できます。 ## SDK、CLI、API のバージョン管理 SDK と Stripe CLI には、すべてのリクエストの API バージョンが自動的に含まれます。SDK または CLI のバージョンを更新すると、Stripe はリクエストとレスポンスの API バージョンを同時に更新します。 #### SDK や CLI を使用せず Stripe-Version を含める API `/v2` 名前空間に対する API リクエストのすべてに `Stripe-Version` ヘッダーを含め、基礎となる API バージョンを指定する必要があります。 例えば、API バージョン `2024-09-30.acacia` を使用する curl リクエストは次のようになります。 ```bash curl -G https://api.stripe.com/v2/core/event_destinations \ -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: 2024-09-30.acacia" \ ``` ## v1 と v2 の名前空間の API を同じ導入で使用する 同じ導入であれば、`/v1` または `/v2` 名前空間の API を自由に組み合わせて使用できます。 #### Java ```java import com.stripe.StripeClient; StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}"); // Call a v2 API EventDestination eventDestination = stripe.v2().core().eventDestinations().retrieve("ed_123"); // Call a v1 API Customer customer = stripe.customers().retrieve("cus_123"); ``` 公式の SDK または CLI を使用していない場合は、必ず API コールの URL パスに名前空間を含めます。以下に例を示します。 ```bash # Call a v2 API curl https://api.stripe.com/v2/core/event_destinations # Call a v1 API curl https://api.stripe.com/v1/charges -d amount=2000 -d currency=usd ``` ## リストのページ分割 `/v2` 名前空間の API (`GET /v2/core/event_destinations` など) には、`/v1` 名前空間のものとは異なるページ分割インターフェイスが含まれます。 - `previous_page_url` プロパティは、リストの前のページを取得するための URL を返します。前のページがない場合、値は `null` になります。 - `next_page_url` プロパティは、リストの次のページを取得するための URL を返します。これ以上ページがない場合、値は `null` になります。 これらの URL を使用して、SDK を使用せずにリクエストを行うことができます。逆に、SDK を使用する場合、SDK が自動ページ分割を自動的に処理するため、これらの URL を使用する必要はありません。 最初のリクエストの後でリストフィルターを変更できません。 #### Java ```java StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}"); EventDestinationListParams params = EventDestinationListParams.builder().build(); for (EventDestination eventDestination : stripe.v2().core().eventDestinations().list(params).autoPagingIterable()) { // process event destination object } ``` ## API リクエストでクエリパラメーターを使用する リストエンドポイントでフィルターを使用して結果を制約します。サポートされている GET エンドポイントで [include](https://docs.stripe.com/api-includable-response-values.md) パラメーターを使用して、レスポンスに追加のフィールドを返します。フィルターと include パラメーターを使用すると、値の配列を渡すことができます。(サーバー側の SDK や CLI を使用しない) ダイレクト API リクエストを行う場合は、単一の値のみを渡す場合でも、常に角括弧表記を使用して配列値のインデックスを指定する必要があります。 たとえば、`applied_configuration` が `merchant` のすべての [Accounts](https://docs.stripe.com/api/v2/core/accounts.md) をリストするには、以下を渡します。 ```bash curl -G https://api.stripe.com/v2/core/accounts?applied_configurations[0]=merchant -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: 2025-12-15.clover" \ ``` 設定が `merchant` または `customer` のすべてのアカウントをリストするには、次の構文を使用します。 ```bash curl -G https://api.stripe.com/v2/core/accounts?applied_configurations[0]=merchant&applied_configurations[1]=customer -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: 2025-12-15.clover" \ ``` include パラメーターにも同じパターンを使用できます。たとえば、レスポンスに複数のフィールドを含めるには、以下の構文を使用します。 ```bash curl -G https://api.stripe.com/v2/core/accounts/:id?include[0]=requirements&include[1]=defaults&include[2]=identity -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: 2025-12-15.clover" \ ``` クエリパラメーター内に配列がネストされている場合もあります。たとえば、入金方法のリストを取得するには、値の配列を指定して、`usage_status[payments]` のネストされたフィールドでフィルタリングします。 ```bash curl -G https://api.stripe.com/v2/money_management/payout_methods?usage_status[payments][0]=eligible&usage_status[payments][1]=invalid -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: 2025-12-15.preview" \ ``` ## べき等 `/v2` 名前空間の API では、べき等の動作に対するサポートが改善されており、同じべき等キーを使用してリクエストが複数回実行されたときの想定外の副作用を防止します。API が同じべき等キーを使用する 2 つのリクエストを受信すると以下のようになります。 - 最初のリクエストが成功すると、API は新たに加えられた変更をスキップし、更新されたレスポンスを返します。 - 最初のリクエストが失敗 (または部分的に失敗) すると、API はその失敗したリクエストを再実行して、新しいレスポンスを返します。 - まれに、べき等の再実行が成功しなくなった場合、API は理由を説明するエラーを返します。 以下の条件をすべて満たす場合、リクエストは以前送られた別のリクエストのべき等であると判定されます。 - 同じ API に同じべき等キーを使用していること - 同じアカウントまたはサンドボックス内で発生していること - それぞれのリクエストが 30 日以内の間隔で発生していること べき等キーを指定するには、`Idempotency-Key` ヘッダーを使用して、操作を表す一意の値 (UUID を推奨) を指定します。キーが指定されない場合、Stripe は UUID を自動的に生成します。 `POST` と `DELETE` の API v2 リクエストはすべて、べき等キーを受け入れ、べき等を利用して動作します。`GET` リクエストは、定義により、べき等性を備えているため、べき等キーを送信しても効果はありません。 ## API v1 と API v2 のべき等の違い API v1 と API v2 のべき等には、重要な違いがいくつかあります。 - API v1 は、`POST` リクエストでのみべき等の再実行をサポートしています。API v2 は、すべての `POST` リクエストと `DELETE` リクエストをサポートしています。 - 以下の場合、リクエストは以前送られた別のリクエストのべき等であると判定されます。 - API v1 は、これらが同じべき等キーを使用し、互いに 24 時間以内に発生した場合。 - API v2 同じべき等キーを使用し、同じ API に対して作成され、同じアカウントまたはサンドボックス内で発生し、さらにそれぞれのリクエストが 30 日以内の間隔で発生している場合。 - 2 つのリクエストに同じべき等キーを指定する場合は以下のようになります。 - API v1 は、最初の API リクエストがエラーであった場合でも、以前保存されたレスポンスを常に返します。 - API v2 は、副作用 (API コールの結果として発生する外部の変更または観測可能な動作) を発生させることなく、失敗したリクエストを再試行し、更新されたレスポンスを提供します。 ### べき等リクエストを作成する SDK を使用すると、API リクエストで `idempotencyKey` プロパティを使用してべき等キーを指定できます。 例えば、特定のべき等キーを使用して API リクエストを作成するには以下のようになります。 #### Java ```java StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}"); String idempotencyKey = "unique-idempotency-key"; Example result = stripe.v2().examples().create( ExampleCreateParams.builder() .setName("My example") .build(), RequestOptions.builder() .setIdempotencyKey(idempotencyKey) .build()); ``` SDK または CLI を使用していない場合、リクエストには `Idempotency-Key` ヘッダーを含めることができます。 ```bash curl https://api.stripe.com/v2/examples \ -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: {{STRIPE_API_VERSION}}" \-H "Idempotency-Key: unique-idempotency-key" \ -d ``` ## 制限事項 - すべての `/v2` API が[テスト環境のサンドボックス](https://docs.stripe.com/testing-use-cases.md#compare)に対応するわけではありません。`/v2` エンドポイントは、いつでもサンドボックスでテストできます。 - Stripe は現在、`/v2` エンドポイントおよびリソースを使用して thin イベントのみを生成しています。 - API v2 によって生成されたリクエストログは、開発者ダッシュボードではなく [Workbench](https://docs.stripe.com/workbench.md) でのみ確認できます。