API からレポートを実行する

ダッシュボードの財務レポートには、さまざまな会計および照合用に CSV 形式でダウンロード可能なレポートが用意されています。これらのレポートは API を介して利用できるため、自動的に実行するようにスケジュールすることも、関連するレポートファイルを会計目的で受信する必要があるときに実行することもできます。

レポートタイプ

ダッシュボードの各財務レポートは、さまざまな CSV 形式でダウンロードできます。次のレポートの利用可能なダウンロードはすべて、API から入手することもできます。

• 残高
• 入金の照合
• 税金
• Connect プラットフォーム

パラメーターを実行する

各レポートには、レポート実行の作成時に指定する必須とオプションの両方のパラメーターがあります。レポートの実行時は次について注意してください。

• ほぼすべてのレポートタイプで、実行パラメーター 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 タイムゾーンデータベースをご覧ください。
• オプションパラメーター currency と report_category は、指定された値に一致する行にのみ結果を絞り込みます。
• レポートはデフォルトの列セットを返しますが、ほとんどのレポートタイプでは、オプションの columns パラメーターと列名のリストを含めることで、出力の列の選択と順序をカスタマイズできます。

データの可用性

Stripe は半日単位で、レポート用のデータを準備します。レポートオプションには、各レポートの予測処理時間とデータの可用性に関する詳細が示されます。

特定のレポートタイプで使用可能なデータの期間をプログラムで決定するには、対象の ReportType オブジェクトを取得します。たとえば、残高サマリーレポートの ID は balance.summary.1 であるため、次のようにオブジェクトを取得できます。

curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

以下のレスポンス例では、フィールド data_available_start と data_available_end はこのレポートタイプの有効時間の全範囲を反映しています。 ただし、ほとんどの場合、その範囲内の短い間隔でレポートを実行します。

{
  "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 イベントを発行します。これらのイベントにアクセスするには、Webhook を設定して、reporting.report_type.updated イベントを受信することを明示的に選択する必要があります。‘all events’ をリッスンする Webhook ではこのイベントを受信できません。イベントを受信したら、レポートを実行できます。詳細については、推奨される導入パターンをご覧ください。

レポートの実行の作成とアクセス

ReportRun API オブジェクトは、特定のパラメーターで生成された ReportType のインスタンスを表します。そのタイプの必須パラメーターとオプションパラメーターのリストについては、レポートタイプのドキュメントをご覧ください。たとえば、2020 年 4 月のアクティビティーによる残高変更のサマリーレポートを、次のように作成できます。

curl https://api.stripe.com/v1/reporting/report_runs \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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"で表示されます。

{
  "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 が含まれます。たとえば、完了後に上記レポートの実行を取得した場合、レスポンスは次のようになります。

{
  "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 https://files.stripe.com/v1/files/file_xs8vrJzC/contents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

レポート実行の完了通知

ほとんどの実行は数分で完了します。ただし、データセットのサイズやレポートの対象となる時間範囲によってはそれよりも長くかかることもあります。

リクエストされたレポートの実行が完了すると、Stripe は次の 2 つの Webhook のいずれかを送信します。

• 実行が成功すると、reporting.report_run.succeeded Webhook が送信されます。
• 実行に失敗すると、reporting.report_run.failed Webhook が送信されます (これは稀なことではありますが、Stripe では 500 レスポンスを検出するのと同じ様にこのケースを処理できるように組み込みを準備することをお勧めします)。

いずれのケースでも、Webhook ペイロードには、それぞれ対応する succeeded または failed ステータスが含まれた、更新された ReportRun オブジェクトが含まれます。

自動レポートに推奨される組み込みパターン

reporting.report_type.updated イベントを受信することを明示的に選択する Webhook を設定します。‘all events’ をリッスンする Webhook をはこのイベントを受信しません。

1. 特定のレポートタイプに関する新しい日次データが利用可能になるとすぐに、reporting.report_type.updated Webhook が送信されます。ペイロードには、更新された ReportType オブジェクトが含まれます。通常、レポートタイプごとに 2 つずつ、毎日 20 ～ 30 の Webhook を受信します (ユーザーによって対象になるレポートは異なります)。
2. 必要なレポートタイプとデータ可用性の範囲についての reporting.report_type.updated Webhook を受信したら、レポートの実行を作成します。レスポンスには、status=pending で初期化された新しい ReportRun オブジェクトが含まれます。
3. 実行が完了すると、reporting.report_run.succeeded Ｗebhook が送信されます。この Webhook には、ネストされたフィールド、result.url が含まれます (前述のように稀ではありますが、万が一失敗した場合には、reporting.report_run.failed イベントが代わりに送信されます)。
4. API キーを使用して、result.url にあるファイルコンテンツにアクセスします。