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_09l3shTSTKHYCzzZZsiLl2vA
:

以下いかのレスポンス例れいでは、フィールド 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_09l3shTSTKHYCzzZZsiLl2vA
: \
  -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_09l3shTSTKHYCzzZZsiLl2vA
:

レポート実行じっこうの完了かんりょう通知つうち

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

リクエストされたレポートの実行じっこうが完了かんりょうすると、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 にあるファイルコンテンツにアクセスします。