> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cbpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 账户对账单

> 合并对账单：供你的网页使用的 JSON、可下载的 PDF 和 Excel，随时可交给你的会计

对账单将一个账户在某个期间内的**所有**流水 — 出款、入款、加密货币充值与提现、内部转账、银行卡消费、余额兑换、银行业务操作和服务费 — 合并为一份可审计的文档。同一个端点提供三种格式：

| 格式         | 用途                       | 请求方式          |
| ---------- | ------------------------ | ------------- |
| `json`（默认） | 在你的网页/应用中渲染对账单           | `format=json` |
| `pdf`      | 带 CBPay 品牌的正式文档          | `format=pdf`  |
| `xlsx`     | 按分区分工作表、带筛选和数值单元格的 Excel | `format=xlsx` |

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    ledger["不可变账本<br/>（每笔流水均带 balance_after）"] --> build["对账单组装<br/>汇总 + 分类明细 + 逐笔明细"]
    build --> json["JSON<br/>（网页视图）"]
    build --> pdf["品牌化 PDF<br/>（下载）"]
    build --> xlsx["多工作表 Excel<br/>（下载）"]
    build --> check{"对账核验：<br/>期初 + 流入 − 流出<br/>= 期末"}
```

## 请求对账单

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# JSON for your front end
curl "https://api.qbank.cl/platform/v1/reports/statement?from=2026-01-01&to=2026-07-07" \
  -H "Authorization: Bearer <token>"

# Downloadable PDF (CBPay branding)
curl -OJ "https://api.qbank.cl/platform/v1/reports/statement?from=2026-01-01&to=2026-07-07&format=pdf" \
  -H "Authorization: Bearer <token>"

# Downloadable Excel
curl -OJ "https://api.qbank.cl/platform/v1/reports/statement?from=2026-01-01&to=2026-07-07&format=xlsx" \
  -H "Authorization: Bearer <token>"
```

* `from` / `to`：`YYYY-MM-DD` 格式的日期，均含当日，UTC 时区。最大范围：400 天。
* `lang=es|en`：PDF/Excel 的语言（默认 `es`）。
* 文件以 `Content-Disposition: attachment` 送达，文件名为 `cartola_cbpay_<account>_<from>_<to>.pdf/.xlsx`。

## 包含哪些内容

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "account": { "account_id": "…", "display_name": "Example Company SpA", "type": "company" },
  "period": { "from": "2026-01-01", "to": "2026-07-07", "timezone": "UTC" },
  "generated_at": "2026-07-07T15:00:00Z",
  "summary": {
    "opening_balance": "0.000000",
    "total_in": "985633.540000",
    "total_out": "38099.870000",
    "net_change": "947533.670000",
    "closing_balance": "947533.670000",
    "balanced": true,
    "counts": { "payouts": 51, "payins": 12, "crypto_deposits": 18, "transfers": 4, "movements": 771 },
    "fees_by_service": { "payout": "15.300000", "funding": "897.550000" },
    "total_fees": "912.850000"
  },
  "breakdown": {
    "by_product": [ { "product": "payouts", "count": 51, "usdt_in": "0.000000", "usdt_out": "38099.870000", "fees": "15.300000" } ],
    "by_country": [ { "flow": "payouts", "country": "BO", "currency": "BOB", "count": 14, "local_amount": "28748.58", "usdt_amount": "2902.210000" } ],
    "by_currency": [ { "currency": "BOB", "payout_local": "28748.58", "payin_local": "700.00" } ],
    "by_month": [ { "month": "2026-01", "usdt_in": "985633.540000", "usdt_out": "35100.000000" } ]
  },
  "payouts": [ { "created_at": "…", "payout_id": "…", "country": "BO", "beneficiary": "Juan Quispe", "local_amount": "90.00", "fx_rate": "6.91", "usdt_amount": "13.024600", "fee": "0.300000", "fee_percent": "0.200000", "fee_fixed": "0.100000", "total_debit": "13.324600", "status": "completed" } ],
  "payins": [ { "…": "…" } ],
  "card_transactions": [ { "created_at": "…", "transaction_id": "…", "card_id": "…", "kind": "purchase", "merchant": "AMAZON.COM", "amount_usd": "25.00", "spend_asset": "USDT", "spend_amount": "25.000000", "status": "settled" } ],
  "swaps": [ { "created_at": "…", "swap_id": "…", "from_asset": "USDT", "to_asset": "BTC", "from_amount": "10.000000", "to_amount": "0.00015433", "rate": "0.00001543", "status": "completed" } ],
  "banking_operations": [ { "created_at": "…", "operation_id": "…", "direction": "out", "type": "wire", "currency": "USD", "amount": "150.00", "counterparty": "Acme Inc", "status": "completed" } ],
  "assets": [
    {
      "asset": "GOLD",
      "opening_balance": "0.000000",
      "total_in": "12.500000",
      "total_out": "2.000000",
      "net_change": "10.500000",
      "closing_balance": "10.500000",
      "balanced": true,
      "movements": [ { "type": "adjustment", "amount": "12.500000", "balance_after": "12.500000", "created_at": "…" } ]
    }
  ],
  "crypto_deposits": [ { "chain": "tron", "asset": "USDT", "tx_id": "…", "usdt_gross": "100.000000", "fee": "1.000000", "usdt_credited": "99.000000", "balance_after": "99.000000" } ],
  "crypto_withdrawals": [ { "…": "…" } ],
  "transfers": [ { "direction": "sent", "counterparty": "Ana Perez", "asset": "USDT", "amount": "25.000000" } ],
  "service_charges": [ { "type": "banking_fee", "service": "banking_customer", "fee_model": "fixed", "amount": "-0.500000", "balance_after": "98.500000" } ],
  "movements": [ { "type": "funding", "amount": "99.000000", "balance_after": "99.000000", "created_at": "…" } ]
}
```

分区：

1. **`summary`** — 期初余额、流入、流出、期末余额、按服务分类的手续费，以及 **USDT 余额**（运营货币）的 `balanced` 标志。
2. **`assets`** — 每个有活动或余额的非 USDT 币种各有一个已对账的分区（USDC、BTC、GOLD，以及若使用 Banking，则包括你银行账户的 `BANK_USD`/`BANK_EUR` 镜像）：期初/期末余额、流入、流出、各自的 `balanced` 标志及其流水，按各币种的精度呈现。如果你只使用 USDT，此分区为空。
3. **`breakdown`** — 按产品、按国家（出款和入款，含本地金额和 USDT）、按法币币种和按月份。
4. **按产品的明细** — 出款（收款人、汇率和扣款）、入款（按模式）、加密货币（含 `tx_id` 及其 `asset`）、转账（含对手方和 `asset`）、银行卡消费（`card_transactions`，含商户和消费余额）、余额兑换（`swaps`）、银行业务操作（`banking_operations`）和服务费（含退款）。
5. **`movements`** — 原始 USDT 账本：每笔流水均带 `balance_after`。这是审计师用来核对全部数据的分区（其他币种的流水位于各自的 `assets` 分区内）。

<Note>
  **透明的手续费。** 在出款、入款和加密货币提现中，当手续费由百分比和固定部分组成时，对账单会将其拆分为 `fee_percent` 和 `fee_fixed`（两者之和精确等于 `fee`）。独立收费（合规、钱包、银行业务、身份核验、银行卡）始终为固定金额，并带有 `fee_model: "fixed"` — PDF/Excel 中标记为 **Fixed Com**。早于该字段的历史操作只显示合并后的 `fee`。
</Note>

## 如何对账（给你的会计）

对账单满足一个精确的会计恒等式，没有任何舍入：

```
opening_balance + total_in − total_out = closing_balance
```

* `balanced: true` 确认该恒等式与账本相符 — 无论是 USDT 汇总还是每个 `assets` 分区内部（每个币种单独对账；不同币种的金额绝不相加）。
* 每一行 `movements` 都携带结果余额（`balance_after`）：你可以从期初到期末逐行跟踪余额变化。
* 一个期间的期末余额与下一个期间的期初余额一致。
* 手续费绝不隐藏在金额中：每笔操作分别显示总额、手续费和净额，`fees_by_service` 汇总所有手续费。
* 在 Excel 文件中，**Movements** 工作表使用真正的数值单元格：无需任何清洗即可求和/做透视表。

## 面向管理员（组织管理员）

CBPay 团队可以生成其任一账户的对账单：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.qbank.cl/platform/v1/accounts/{accountID}/reports/statement?from=2026-01-01&to=2026-07-07&format=pdf" \
  -H "X-API-Key: <pk_org_admin>"
```

管理员视图还包含该期间的额外运营信息（详见管理文档）。

## 错误

| HTTP | `error`          | 原因                                 |
| ---- | ---------------- | ---------------------------------- |
| 400  | `invalid_range`  | 日期缺失/无效、`to` 早于 `from`，或范围超过 400 天 |
| 400  | `invalid_format` | `format` 不是 `json`、`pdf`、`xlsx` 之一 |
| 404  | `not_found`      | 账户不存在（仅组织管理员）                      |