# Reports API の仕組み プログラムで Stripe の財務レポートにアクセスして、消し込みのワークフローを自動化します。 > Stripe Data Pipeline を使用すると、数回クリックするだけで Stripe データとレポートを Snowflake や Amazon Redshift に自動的に送信できるようになりました。[もっと知る](https://stripe.com/data-pipeline) ダッシュボードの[財務レポート](https://dashboard.stripe.com/reports)には、さまざまな会計および照合用に CSV 形式でダウンロード可能なレポートが用意されています。これらのレポートは API を介して利用できるため、自動的に実行するようにスケジュールすることも、関連するレポートファイルを会計目的で受信する必要があるときに実行することもできます。 ## レポートタイプ ダッシュボードの各財務レポートは、さまざまな CSV 形式でダウンロードできます。次のレポートの利用可能なダウンロードはすべて、API から入手することもできます。 - [残高](https://docs.stripe.com/reports/report-types/balance.md) - [入金の照合](https://docs.stripe.com/reports/report-types/payout-reconciliation.md) - [手数料レポートタイプ](https://docs.stripe.com/reports/report-types/fees.md) - [税金](https://docs.stripe.com/reports/report-types/tax.md) - [Connect プラットフォーム](https://docs.stripe.com/reports/report-types/connect.md) > #### CSV と API の金額形式の違い > > CSV レポートは、「主要」通貨単位の金額を小数としてフォーマットします。たとえば、CSV では、10 USD はドルとセント (`10.00`) としてフォーマットされます。これは、通貨の「補助」単位 (アメリカのセント) で金額を整数として指定する Stripe API とは異なります。この API では、10 USD をセント (`1000`) としてフォーマットします。 ### パラメーターを実行する 各レポートには、レポート実行の作成時に指定する必須とオプションの両方のパラメーターがあります。レポートの実行時は次について注意してください。 - ほぼすべてのレポートタイプで、実行パラメーター `interval_start` (この値を含む) と `interval_end` (この値を含まない) を Unix タイムスタンプで指定する必要があります。 - 対応する各レポートタイプのリソースには、`data_available_start` フィールドと `data_available_end` フィールドがあります。実行で以下の制約が満たされない場合、API は無効なリクエストエラー (ステータスコード `400`) を返します。 - `interval_start` と `interval_end` の値は、`data_available_start` と `data_available_end` (開始日、終了日を含む) にある必要があります。 - `interval_start` の値は、`interval_end` より「前」の日付 (同日は不可) である必要があります。 - `timezone` パラメーターを持つ `ReportType` のタイムゾーンでのみレポートをダウンロードできます。そのためには、`ReportRun` オブジェクトを作成して、目的の TZ データベースのタイムゾーン名を指定します。`timezone` パラメーターはオプションであり、指定されていない場合はデフォルトで UTC になります。有効なタイムゾーン値のリストについては、[IANA タイムゾーンデータベース](https://www.iana.org/time-zones)をご覧ください。 - オプションパラメーター `currency` と `report_category` は、指定された値に一致する行にのみ結果を絞り込みます。 - レポートはデフォルトの列セットを返しますが、ほとんどのレポートタイプでは、オプションの `columns` パラメーターと列名のリストを含めることで、出力の列の選択と順序をカスタマイズできます。 ## データの可用性 Stripe は半日単位で、レポート用のデータを準備します。[レポートオプション](https://docs.stripe.com/reports/options.md#data-availability)には、各レポートの予測処理時間とデータの可用性に関する詳細が示されます。 特定のレポートタイプで使用可能なデータの期間をプログラムで決定するには、対象の `ReportType` オブジェクトを[取得](https://docs.stripe.com/api.md#retrieve_reporting_report_type)します。たとえば、 **残高サマリー** レポートの ID は `balance.summary.1` であるため、次のようにオブジェクトを取得できます。 #### curl ```bash curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \ -u <>: ``` 以下のレスポンス例では、フィールド `data_available_start` と `data_available_end` はこのレポートタイプの有効時間の全範囲を反映しています。 ただし、ほとんどの場合、その範囲内の短い間隔でレポートを実行します。 ```json { "id": "balance.summary.1", "name": "Balance summary", "version": "1", "object": "reporting.report_type", "data_available_start": 1519862400, "data_available_end": 1517356800, "updated": 1517382720, } ``` `date_available_start` などのタイムスタンプは、Unix エポックからの経過秒数で計測されます。たとえば、`1519862400` は `2018-03-01 00:00` のタイムスタンプを表します。 ### 新しいデータの通知 レポートタイプで新しいデータが利用可能になると、Stripe は更新された `ReportType` オブジェクトを使用して `reporting.report_type.updated` イベントを発行します。これらのイベントにアクセスするには、`reporting.report_type.updated` イベントの受信を明示的に選択する [Webhook を設定](https://docs.stripe.com/webhooks.md#register-webhook)する必要があります。「すべてのイベント」の主張が認められた Webhook は受信しません。 Webhook トラフィックを減らすため、Stripe はこれらのイベントを[Connect Webhook エンドポイント](https://docs.stripe.com/connect/webhooks.md)に送信しません。イベントを受信したら、レポートを実行できます。詳細については、[推奨の導入パターン](https://docs.stripe.com/reports/api.md#integration-pattern)をご覧ください。 ## レポート実行の作成とアクセス `ReportRun` API オブジェクトは、特定のパラメーターで生成された `ReportType` のインスタンスを表します。そのタイプの必須パラメーターとオプションパラメーターのリストについては、[レポートタイプ](https://docs.stripe.com/reports/api.md#report-types)のドキュメントをご覧ください。たとえば、2020 年 4 月の**アクティビティーによる残高変更のサマリー**レポートを、次のように[作成](https://docs.stripe.com/api/reporting/report_run/create.md)できます。 #### curl ```bash curl https://api.stripe.com/v1/reporting/report_runs \ -u <>: \ -d "report_type"="balance_change_from_activity.itemized.3" \ -d "parameters[interval_start]"=1577865600 \ -d "parameters[interval_end]"=1580544000 \ -d "parameters[timezone]"="America/Los_Angeles" \ -d "parameters[columns][]"="created" \ -d "parameters[columns][]"="reporting_category" \ -d "parameters[columns][]"="net" # Timestamps are for 2020-01-01 00:00 PST and 2020-02-01 00:00 PST. # The columns parameter is optional. A default set of columns will be provided if you don't specify a value. # Note that a live-mode API key is required. ``` オブジェクトが作成されると、最初は次のように `status="pending"`で表示されます。 ```json { "id": "frr_123", "object": "reporting.report_run", "livemode": true, "report_type": "balance_change_from_activity.itemized.3", "parameters": { "columns": [ "created", "reporting_category", "net" ], "interval_start": 1577865600, "interval_end": 1580544000, "timezone": "America/Los_Angeles" }, "created": 1580832900, "status": "pending", "result": null } ``` 実行が完了すると、Stripe がオブジェクトを更新し、`status` が `succeeded` になります。ネストされた `result` オブジェクトもあり、API キーを使用してファイルにアクセスするために使用できる URL が含まれます。たとえば、完了後に上記レポートの実行を[取得](https://docs.stripe.com/api/reporting/report_run/retrieve.md)した場合、レスポンスは次のようになります。 ```json { "id": "frr_123", "object": "reporting.report_run", "livemode": true, "report_type": "balance_change_from_activity.itemized.3", "parameters": { "columns": [ "created", "reporting_category", "net" ], "interval_start": 1577865600, "interval_end": 1580544000, "timezone": "America/Los_Angeles" }, "created": 1580832900, "status": "succeeded", "succeeded_at": 1580832960, "result": { "id": "file_xs8vrJzC", "object": "file", "url": "https://files.stripe.com/v1/files/file_xs8vrJzC/contents", "created": 1580832960, "purpose": "report_run", "size": 53075, "type": "csv" } } ``` ファイルのコンテンツを取得するには、次のように API キーを使用して `result.url` で指定されたファイルにアクセスします。 #### curl ```bash curl https://files.stripe.com/v1/files/file_xs8vrJzC/contents \ -u <>: ``` ### レポートの実行通知 ほとんどの実行は数分で完了します。ただし、データセットのサイズやレポートの対象となる時間範囲によってはそれよりも長くかかることもあります。 リクエストされたレポートの実行が完了すると、Stripe は次の 2 つの Webhook のいずれかを送信します。 - 実行が成功すると、`reporting.report_run.succeeded` Webhook が送信されます。 - 実行に失敗すると、`reporting.report_run.failed` Webhook が送信されます (これは稀なことではありますが、Stripe では `500` レスポンスを検出するのと同じ様にこのケースを処理できるように組み込みを準備することをお勧めします)。 いずれのケースでも、Webhook ペイロードには、それぞれ対応する `succeeded` または `failed` ステータスが含まれた、更新された `ReportRun` オブジェクトが含まれます。 > ダッシュボードから実行したレポートは、レポート Webhook イベントをトリガーしません。 ## 自動レポート導入パターン `reporting.report_type.updated` イベントを受信することを明示的に選択する Webhook を設定します。`all events` をリッスンする Webhook はこのイベントを受信しません。 > [サンドボックス](https://docs.stripe.com/sandboxes.md)を使用している場合、`reporting.report_type.updated` イベントは受信されません。 1. 特定のレポートタイプに関する新しい日次データが利用可能になるとすぐに、`reporting.report_type.updated` Webhook が送信されます。ペイロードには、更新された `ReportType` オブジェクトが含まれます。通常、レポートタイプごとに 2 つずつ、毎日 20 ～ 30 の Webhook を受信します (ユーザーによって対象になるレポートは異なります)。 1. 必要なレポートタイプとデータ可用性の範囲についての `reporting.report_type.updated` Webhook を受信したら、[レポートの実行を作成](https://docs.stripe.com/api/reporting/report_run/create.md)します。レスポンスには、`status=pending` で初期化された新しい `ReportRun` オブジェクトが含まれます。 1. 実行が完了すると、`reporting.report_run.succeeded` Ｗebhook が送信されます。この Webhook には、ネストされたフィールド、`result.url` が含まれます (前述のように稀ではありますが、万が一失敗した場合には、`reporting.report_run.failed` イベントが代わりに送信されます)。 1. API キーを使用して、`result.url` にあるファイルコンテンツにアクセスします。 Stripe は各アカウントの同時レポート実行を監視します。インフラストラクチャーを保護し、すべてのユーザーのサービス品質を確保するために、同時に実行されるレポートが多すぎる場合はリクエストを制限することがあります。レート制限エラー（HTTP 429）が発生した場合は、保留中のレポートの実行が完了するまで待ってから、新しいレポートをリクエストしてください。