# 报告 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 美元格式化为美元和美分 (`10.00`)。在 Stripe API 中，您可以以整数指定货币的_次要_单位（美分），这是两者的不同。在 API 中，10 美元会格式化为美分 (`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)中提供了各报告的预计处理时间和数据可用性的详细信息。

要程序化地确定给定报告类型的可用数据的时间范围，请[检索](https://docs.stripe.com/api.md#retrieve_reporting_report_type)相关的 `ReportType` 对象。例如，**余额摘要**报告有个 ID `balance.summary.1`，因此您可以按照如下方式检索对象：

#### curl

```bash
curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \
  -u <<YOUR_SECRET_KEY>>:

```

在下面的响应示例中，字段 `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,
}
```

自 Unix 时代以来，时间戳以秒为单位进行测量，例如 `date_available_start`。例如，`1519862400` 表示时间戳 `2018-03-01 00:00`。

### 新数据通知

当报告类型有新数据可用时，Stripe 会发布一个 `reporting.report_type.updated` 事件，并附带更新后的 `ReportType` 对象。要访问这些事件，您必须配置一个明确选择接收 `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 <<YOUR_SECRET_KEY>>: \
  -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` 对象，包含一个 URL，您可以在这里用您的 API 密钥访问文件。例如，如果您想在运行完成后[检索](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 <<YOUR_SECRET_KEY>>:

```

### 报告运行通知

多数几分钟即可运行完毕。但是，有些运行时间会长一些——取决于您的总数据集的大小，以及您的报告涵盖的时间范围。

当请求的报告成功运行时，Stripe 会发送这两个 webhook 中的一个：

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

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

> 从管理平台运行的报告不会触发 Webhook 事件上报操作。

## 自动化报告集成模式

配置一个显式接收 `reporting.report_type.updated` 事件的 Webhook。监听`所有事件`的 Webhook 将不会收到这些事件。

> 如果您使用[沙盒](https://docs.stripe.com/sandboxes.md)，您将无法接收 `reporting.report_type.updated` 事件。

1. 一旦给定类型新的一天的数据可用，即发送一个 `reporting.report_type.updated` webhook。有效载荷包括更新后的 `ReportType` 对象。您通常每天会收到 20-30 个 webhooks，每个报告类型两个。（不同的用户适用不同的类型。）

1. 一旦收到期望的报告类型的 `reporting.report_type.updated` webhook 和数据可用范围，即[创建一次报告运行](https://docs.stripe.com/api/reporting/report_run/create.md)。响应包含新的 `ReportRun` 对象，该对象初始化为 `status=pending`。

1. 运行完成后，会发送一个 `reporting.report_run.succeeded` webhook。此 Webhook 包括嵌套字段 `result.url`。（如上所述，在极少失败的情况下，我们将发送一个 `reporting.report_run.failed` 事件。）

1. 用您的 API 密钥从 `result.url` 访问文件内容。

Stripe 会监控各账户同时运行的报表任务数量。为了保护系统资源并确保所有用户的服务质量，当同时运行的报表过多时，我们可能会限制请求次数。如果遇到速率限制错误 (HTTP 429),请等待部分正在进行的报表运行完成后，再发起新请求。