账户中心 › API 参考 › 报表导出

建一个对账报表导出任务（异步 · 出 CSV）

POST /v1/reports scope: merchant:read

商户自身需 x-idempotency-key

为什么是异步任务而不是同步下载

一个月的分录动辄十万行，同步生成会在 CPU 时限上撞墙 ——

而撞墙的表现是「点了没反应」。所以这里只建任务（201 +

status: queued），文件到 GET /v1/reports/{id}/content 去取。

队列靠调用推进，没有定时任务

建任务时我方会在这次请求的后台推一步，GET /v1/reports/{id}

也会顺带推一步。小报表往往在你第一次轮询之前就好了。

⚠ 别建完就不管 —— 建了不轮询的任务可能一直排在队列里。

这条线不发 Webhook：报表好了不会推你，请轮询。

（凭空给你一条 report.ready 只会变成一条谁都不会触发的死事件。）

`kind` —— 认不出的当场拒

`kind`	是什么
`daily`	逐日 × 业务线 × 资产的日汇总
`pnl`	整个窗口的逐线合计（综合经营）
`line:<line>`	同上，只看一条线
`statements`	逐单的业务扣款明细

<line> 取八条之一：qrpay · remit · card · earn ·

exchange · withdraw · transfer · deposit。

认不出的 kind 当场 400 invalid_request —— 放行的话任务建得出来、

生成器再判失败，你拿到的是一次「排队 30 秒然后失败」，

而 400 直接告诉你名字写错了。

`days`：超范围静默回落 30，不报错

合法区间 1..180（不设上限等于把全表扫的能力开放出去）。

非数字、0、200 都不会报错，一律按 30 处理 ——

⚠ 所以请读 201 响应里的 days，那才是真正生效的窗口，

而不是你传进来的那个数。

在途上限 3

queued + building 合计 ≥ 3 时回 400 limit_exceeded

（带 limit_type: report_exports_in_flight、limit_scope: merchant）。

一次导出是一次全窗口聚合扫描 —— 没有这道闸，一个写错的循环能让你的

报表队列吃掉整个 Worker 的 CPU，而受害的是你自己的下单接口。

为什么归 `merchant:read` 而不是一把新 scope

导出件里的数据与这把 scope 已经给出去的完全一样（对账单、逐线

聚合），只是换了个格式。新开一把 scope 会让同一份数据有两道权限，

而你拿不到导出件时没有任何办法知道自己缺的是哪一把。

它是 POST 但不动钱 —— 与 POST /v1/merchant/deposit-addresses

同一条判断。

字段	类型	必填	说明
`x-idempotency-key`	string	必填	UUID v4。24 小时内同键 + 同 body 拿回首次那份 `201` （原样回放，带 `X-Idempotent-Replay: true` 响应头），不会建第二份。 ⚠ 超过 24 小时同键会真的再建一个任务，并占掉一个在途名额 —— 这条线没有第二层幂等。每次导出用一把新键。

请求体

字段	类型	必填	说明
`kind`	string	必填	`daily` / `pnl` / `statements` / `line:<line>`。大小写敏感，认不出回 `invalid_request`。
`days`	integer	可选	窗口天数，`1..180`，缺省 30。超范围或非数字静默回落到 30 —— 以响应里的 `days` 为准。

响应

201任务已建（status 恒为 queued）。days 是生效后的值。

{
  "id": "rep_4c8a10d2-91f7-4a3e-b0c6-52d8e7f19b34",
  "kind": "statements",
  "status": "queued",
  "days": 30,
  "created_at": "2026-08-13T05:00:00.000Z"
}

400invalid_request body 非 JSON / kind 认不出（含未登记的 line:<line>）· limit_exceeded 在途任务已有 3 个（limit_type: report_exports_in_flight · limit_scope: merchant）

403insufficient_scope 缺 merchant:read

409idempotency_key_reused · idempotency_in_progress

请求

curl -X POST 'https://api.zise.com/v1/reports' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "kind": "statements",
    "days": 30
  }'

const res = await fetch("https://api.zise.com/v1/reports", {
  method: "POST",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-idempotency-key": "$IDEMPOTENCY_KEY",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "kind": "statements",
    "days": 30
  }),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();

import requests

res = requests.post(
    "https://api.zise.com/v1/reports",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
        "content-type": "application/json",
    },
    json={
      "kind": "statements",
      "days": 30
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()

req, _ := http.NewRequest("POST", "https://api.zise.com/v1/reports",
    strings.NewReader(`{
  "kind": "statements",
  "days": 30
}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
req.Header.Set("content-type", "application/json")
res, err := http.DefaultClient.Do(req)
// 金额字段用 string 接，不要 float64

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zise.com/v1/reports"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-idempotency-key", "$IDEMPOTENCY_KEY")
    .header("content-type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "kind": "statements",
  "days": 30
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double

$ch = curl_init('https://api.zise.com/v1/reports');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-idempotency-key: $IDEMPOTENCY_KEY',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "kind": "statements",
  "days": 30
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval

201

{
  "id": "rep_4c8a10d2-91f7-4a3e-b0c6-52d8e7f19b34",
  "kind": "statements",
  "status": "queued",
  "days": 30,
  "created_at": "2026-08-13T05:00:00.000Z"
}