从 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 参数是可选的，如果未提供，则默认为世界协调时间。有关有效时区值的列表，请参见 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,
}

自 Unix 时代以来，时间戳以秒为单位进行测量，例如 date_available_start。例如，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 对象，包含一个 URL，您可以在这里用您的 API 密钥访问文件。例如，如果您想在运行完成后检索上述报告，响应是：

{
  "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 会发送这两个 webhook 中的一个：

• 如果运行完全成功，则发送 reporting.report_run.succeeded webhook。
• 如果运行失败，则发送 reporting.report_run.failed webhook。（这应该比较少见，但我们建议准备好此集成，使其能够按照与捕捉 500 响应一样的方式来处理这种情况。）

这两种情况下，Webhook 有效载荷包含上传的 ReportRun 对象，分别包含 succeeded 或 failed 状态。

为自动报告推荐的集成样式

配置一个 Webhook，显式地选择接收 reporting.report_type.updated 事件；侦听 ‘all events’ 的 webhook 不会接收它们。

1. 一旦给定类型新的一天的数据可用，即发送一个 reporting.report_type.updated webhook。有效载荷包括更新后的 ReportType 对象。您通常每天会收到 20-30 个 webhooks，每个报告类型两个。（不同的用户适用不同的类型。）
2. 一旦收到期望的报告类型的 reporting.report_type.updated webhook 和数据可用范围，即创建一次报告运行。响应包含新的 ReportRun 对象，该对象初始化为 status=pending。
3. 运行完成后，会发送一个 reporting.report_run.succeeded webhook。此 Webhook 包括嵌套字段 result.url。（如上所述，在极少失败的情况下，我们将发送一个 reporting.report_run.failed 事件。）
4. 用您的 API 密钥从 result.url 访问文件内容。