余额

查询与 API Key 关联的银行账户余额。

端点

GET /api/external/balance

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

bash

curl -X GET https://api.owem.com.br/api/external/balance \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

json

{
  "worked": true,
  "balance": 3000000,
  "available": 2700000,
  "pending": 300000,
  "currency": "BRL"
}

响应值以基础单位表示

所有响应值都是基础单位整数。要转换为雷亚尔,请除以 10.000。示例：3000000 ÷ 10.000 = R$ 300,00。绝不要使用浮点数。

字段	定义
`balance`	安全余额 = `min(saldo_tigerbeetle, saldo_postgres)`。如果 TB↔PG 出现差异,使用较小值
`available`	`balance - pending` — 实际可用于新操作的余额
`pending`	TigerBeetle 中的待处理借记总和（`account.debits_pending`）

balance 字段在 TigerBeetle 和 PostgreSQL 之间临时出现差异的情况下（例：MED 冻结、部署后调和）保护免受虚高余额的影响。您在这里绝不会看到大于 ledger 系统中实际可用余额的值 — 始终是两个系统中较小的值。

下面每项都是 TigerBeetle 中的待处理转账,在 posted 或 voided 之前会减少 available：

来源	何时出现	何时释放
飞行中的 PIX OUT（TB pending 从 wallet → COSIF in-transit）	在发送期间,等待 BACEN 确认时（通常 ~1,6s）	收到 `pix.payout.confirmed`（已结算）时 posted；收到 `pix.payout.failed` 时 voided
MED 预防性封锁（phantom hold,code 1032）	通过 `ComplianceSyncWorker` 检测到 >R$1k 的 `ACKNOWLEDGED` 违规时	`analysis_result=DISAGREED`（抗辩被接受）时 voided；`AGREED`（PACS.004 退款已执行）时 posted。参见违规。
隔离（stage=5）	PIX OUT 没有 BACEN 响应超过 30 分钟 — 余额处于限制状态	仅在 Owem 储备手动决策后 posted/voided（可能需要数小时或 D+1）。参见 pix-lifecycle。
其他内部 hold	罕见 — 通常与特定 fee 或调整相关	取决于类型

balance < saldo bruto TB 的情况

TB↔PG 差异：在少数情况下（例：部署后修复窗口、session 142 TB-PG equalization 事件）,balance 反映两个系统之间较小的值,直到收敛。我们从不会看到虚高余额；最多在几分钟内低估。

即使 PIX IN 增加,available 可能保持"不动"

如果您看到 balance 上升（入款）但 available 未按比例增长,很可能有活跃的 MED 封锁。查询 GET /api/external/med 列出预防性封锁。每个封锁都源于违规 — 参见违规了解完整流程。

缓存与一致性

余额实时计算（典型延迟 <10ms）— 无缓存。然而,在结算后窗口（webhook pix.charge.paid 之后 <200ms）,PostgreSQL 可能尚未更新。对关键对账,请在查询余额之前等待 webhook。

json

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