对账单

列出账户的交易,支持分页和筛选。

端点

GET /api/external/statement

请求头

头	类型	必填	描述
Authorization	String	是	ApiKey {client_id}:{client_secret}
X-Key-Case	String	否	设为 camelCase 以使用 camelCase 接收响应字段（默认 snake_case）

查询参数

参数	类型	必填	描述	默认
page	Integer	否	页码	1
per_page	Integer	否	每页条数（最大 100）	20
status	String	否	按 payment_status 列筛选。值：settled、rejected、failed、processing	--
type	String	否	按类型筛选（pix、ted、internal）	--
date_from	String	否	起始日期（格式 YYYY-MM-DD）	--
date_to	String	否	截止日期（格式 YYYY-MM-DD）	--

status 接受的值：

• settled：已结算的交易（标准成功）
• rejected：被 BACEN 拒绝
• failed：内部失败或拒绝后失败
• processing：处理中

显示 vs 过滤

响应中 status 字段显示的值可能与过滤器接受的值不同：

• status=2 的记录显示 "pending",但按 status=processing 过滤
• payment_status=nil 和 status=1 的记录显示 "completed",但按 status=settled 过滤

使用上面的过滤值；显示值已归一化以供客户端消费。

示例

curl -X GET "https://api.owem.com.br/api/external/statement?page=1&per_page=20&status=settled&date_from=2026-03-01&date_to=2026-03-07" \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

成功响应 (200)

{
  "worked": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "transaction_id": "7popu57v6us7p6pcicgq12345",
      "end_to_end_id": "E37839059202603071530000001",
      "external_id": "order-9876",
      "type": "pix",
      "status": "settled",
      "amount": 300000,
      "fee_amount": 0,
      "net_amount": 300000,
      "description": "Pedido #1234",
      "direction": "inbound",
      "counterparty_name": "Maria Santos",
      "created_at": "2026-03-07T15:30:00Z",
      "completed_at": "2026-03-07T15:30:02Z"
    },
    {
      "id": "f7e8d9c0-b1a2-4c3d-9e8f-7a6b5c4d3e2f",
      "transaction_id": "PIXOUT20260306x9y8z7w6v5u4",
      "end_to_end_id": "E37839059202603061200000005",
      "external_id": "invoice-4521",
      "type": "pix",
      "status": "settled",
      "amount": 500000,
      "fee_amount": 350,
      "net_amount": 500350,
      "description": "Pagamento fornecedor",
      "direction": "outbound",
      "counterparty_name": "Joao Silva",
      "recipient_key": "12345678901",
      "created_at": "2026-03-06T12:00:00Z",
      "completed_at": "2026-03-06T12:00:03Z"
    }
  ],
  "page": 1,
  "per_page": 20
}

字段	类型	描述
worked	Boolean	true 表示操作成功
data	Array	交易列表
page	Integer	当前页码
per_page	Integer	每页条数

每笔交易的字段

字段	类型	描述
id	String	交易内部 UUID
transaction_id	String	交易公开标识
end_to_end_id	String	BACEN 的 E2E ID
external_id	String	您系统中的标识符。未提供时为 null
type	String	类型（pix、ted、internal）
status	String	交易状态（已归一化用于显示）。参见 查询参数 中的 "显示 vs 过滤" 块。
amount	Integer	金额,以基础单位（÷ 10.000 得到雷亚尔）。300000 = R$ 30,00
fee_amount	Integer	收取的手续费,以基础单位
net_amount	Integer	净额,以基础单位
description	String	交易描述
direction	String	inbound（收款）或 outbound（付款）
counterparty_name	String	对手方姓名
recipient_key	String	收款方 PIX 密钥（仅 outbound）
payer_document	String	付款人 CPF/CNPJ（仅 inbound）。outbound 为 null。
recipient_document	String	收款人 CPF/CNPJ（仅 outbound）。inbound 为 null。
payer_ispb	String	付款机构的 ISPB（仅 inbound）。outbound 为 null。
payer_bank_name	String	通过 ISPB 解析的付款银行名称（仅 inbound）。outbound 为 null。
created_at	String	创建日期（ISO 8601 UTC）
completed_at	String	完成日期（ISO 8601 UTC）。如果尚未结算则为 null。

日期以 UTC 表示

所有日期/时间字段都以 ISO 8601 UTC（后缀 Z）返回。要转换为巴西利亚时间（BRT）,请减去 3 小时。date_from/date_to 过滤器也按 UTC 解释 — 过滤的某一天（date_from=2026-03-07）从 2026-03-07T00:00:00Z 到 2026-03-07T23:59:59Z。

飞行中的交易

当不应用 status 过滤器或应用 status=processing 时,列表的第 1 页包含仍在飞行中的 PIX OUT（outbound_requests 表,stage < 3）。这允许实时对账 — 您可以在 BACEN 处理交易期间看到它,status="pending"、payment_status="processing"、completed_at=null。

当您应用 status=settled 或 status=rejected 时,不会合并 outbound_requests — 仅查询 transactions/failed_transactions 表。这避免了当您只想要最终交易时的重复。

outbound 中的 net_amount 是总和（不是差值）

在 outbound 交易（direction="outbound"）中,net_amount 计算为 amount + fee_amount（账户的总借记,包括手续费）。在 inbound 交易中,net_amount = amount - fee_amount（已扣除手续费的净贷记）。

Outbound 示例：amount=500000、fee_amount=350、net_amount=500350 — 从您账户借记 R$ 50,035。不是 R$ 49,965。

速率限制与轮询

GET /statement 经过 /api/external/* 全局 rate limiter（每个认证 IP 90,000 req/min）。只有 GET /balance 不经过该 limiter。即便如此,请避免对此端点高频轮询 — 建议订阅 webhook（pix.charge.paid、pix.payout.confirmed、pix.payout.failed）以获得实时通知,并使用 /statement 做周期性对账（例：5-15 分钟间隔或 end-of-day batch）。

权限

此端点需要 API Key 有 statement:read 权限。同级端点 GET /api/external/transactions（相同的基础查询,结构几乎相同）需要 transfer:read — 如果您的集成仅使用一组权限,请确认哪个端点接受您的作用域。

错误响应 (401)

{
  "worked": false,
  "errors": {
    "unauthorized": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

分页

per_page 的最大值为 100。要提取大量数据,请递增 page 参数逐页请求,直到响应返回空 data 数组或少于 per_page 的项数。