# 余额、账单与限额 (/zh/docs/conta-digital/statement) 四个路由都使用作用域 `STATEMENT_READ`。 ## 余额 [#余额] [`GET /transactions/balance`](/docs/conta-digital/endpoints/account/get_balance) ```json { "total": 152030, "available": 150530, "blocked": 1500, "blockedBySecurity": 1500, "blockedByWithdraw": 0, "blockedByRefund": 0, "syncedAt": "2026-10-06T18:20:11.004Z" } ``` | 字段 | 说明 | | ----------- | ------------------------------------------------------------------------------------------------------------------------ | | `available` | 可用余额：现在可用于提现、Pix 复制粘贴码付款和退款的金额。它是账单各条目的合计。 | | `blocked` | 在账户中但不能使用的金额，例如进行中的 MED 争议的金额，或仍在处理中的提现、退款或转账的金额。`blockedBySecurity`、`blockedByWithdraw` 和 `blockedByRefund` 按原因分列这部分金额。 | `total` 为 `available + blocked`。所有字段见[查询余额](/docs/conta-digital/endpoints/account/get_balance)。 提现金额加手续费（[限额](#限额)中的 `withdraw`）必须在 `available` 之内。即便如此，提现仍可能以 `WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE` 被拒绝：银行当时无法支付这笔提现。 ## 账单 [#账单] [`GET /transactions/statement`](/docs/conta-digital/endpoints/account/get_statement)?limit=20\&dateFrom=2026-10-01\&trigger=PAYOUT 每一行是一笔影响可用余额的流水，而不是一整笔操作。一笔 R$ 15,00、手续费 R$ 1,05 的已支付收款记为 `+1395`。提现在发起请求时扣出，金额和手续费合在一起（`amount + serviceFee`）。 ```json { "data": [ { "id": "cmu9r1a2b000101s6stmt0002", "entryId": "cmu9r0z9y000001s6entr0002", "amount": -10250, "balanceAfter": 150530, "trigger": "PAYOUT", "description": "Reserva de saque", "originId": "cmu3wd7k1000201s6wdrw0001", "infractionProtocol": null, "gross": 10000, "fee": 250, "status": "SETTLED", "statusDetail": null, "statusReason": null, "statusAt": "2026-10-05T14:40:14.120Z", "payoutOperation": "WITHDRAW", "counterparty": { "name": null, "document": null, "pixKey": "f***@exemplo.com" }, "postedAt": "2026-10-05T14:40:11.002Z" } ], "nextCursor": "cmu9r1a2b000101s6stmt0002", "balance": 150530 } ``` | `trigger` | 该行 | | ------------------------ | ---------------------------------- | | `PAYMENT` | 已支付的收款，已扣除手续费。 | | `DEPOSIT` | 无收款单的入账 Pix，已扣除手续费。 | | `PAYMENT_REFUND` | 退款：金额的扣出，或退款被拒时金额的退回。也包括银行自行发起的退款。 | | `PAYOUT` | 提现或 Pix 复制粘贴码付款在发起请求时的扣款。 | | `PAYOUT_REVERSAL` | 提现失败时，提现金额的退回。 | | `PAYOUT_REFUND_RECEIVED` | 账户发出的 Pix 被退回。 | | `INFRACTION_BLOCK` | MED 争议已发起：金额从可用余额中扣出。 | | `INFRACTION_SETTLED` | 争议成立：金额已退还给付款人。 | | `INFRACTION_RELEASED` | 争议不成立：金额退回，扣除分析费。争议被取消时，全额退回。 | | `INTERNAL_TRANSFER` | 账户间转账，两端都有。`amount` 的正负号表示哪一端。 | * `status` 是提现、退款和转账中操作的当前状态：`PROCESSING`（仍在处理中）、`SETTLED`（已完成）或 `RETURNED`（被拒，金额已退回）。其他条目为 `null`。`description` 记录后不再改变：已完成提现的扣款行仍显示 "Reserva de saque"。 * `statusDetail` 在两种情况下出现。`APPROVAL_REFUSED`：银行未批准该提现，金额仍在可用余额之外，`statusReason` 带有用于展示的消息。`PROVIDER_REFUND`：银行在你没有请求的情况下退还给了付款人。 * `counterparty` 是交易对方。转入时是付款人：收款中是你填写的客户，证件号完整；无收款单的 Pix 中，证件号已脱敏。转出时，`pixKey` 带有已脱敏的目标密钥。争议条目中为 `null`。 * 与 `data` 并列的 `balance` 是当前的可用余额。 ### 筛选 [#筛选] | 筛选 | 说明 | | ------------------- | ----------------------------------------------------------------------------------------------- | | `originId` | Webhook 中的操作 id：`paymentId`、`withdrawId`、`depositId` 或 `transferId`。创建收款、提现或转账时返回的 `id` 在这里不适用。 | | `trigger` | 一个或多个条目类型，以逗号分隔。 | | `dateFrom`、`dateTo` | 不带时间的日期按巴西利亚时间的整天计算。 | | `status` | 来源操作的状态。见下文。 | 筛选条件同时生效。路由不认识的参数会以 `400` 和 `REQUEST_UNKNOWN_QUERY_PARAM` 被拒绝。所有筛选条件见[查询账单](/docs/conta-digital/endpoints/account/get_statement)。 `status` 筛选看的是产生该行的操作的状态，而不是该行的 `status` 字段。它返回处于该状态的操作的所有行，包括退款行。转账行和争议行不在结果中。 ## 限额 [#限额] [`GET /transactions/limits`](/docs/conta-digital/endpoints/account/get_limits) 返回账户当前生效的限额和手续费。金额以分为单位；`feePercentage` 是百分比（`150` = 1.5%）。 ```json { "payment": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 105, "feePercentage": 0 }, "withdraw": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 150 }, "externalPayment": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 }, "refund": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 }, "internalTransfer": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 }, "dailyWithdraw": { "limit": 1000000, "used": 12850 }, "dailyInternalTransfer": { "limit": null, "used": 0 }, "infraction": { "feeFixed": 500, "feePercentage": 0, "blocksBalance": true } } ``` | 区块 | 说明 | | ----------------------- | -------------------------------------------------------- | | `payment` | 收款。 | | `withdraw` | 提现到密钥。最小值和最大值适用于所有 Pix 转出。 | | `externalPayment` | Pix 复制粘贴码付款：沿用提现的限额，手续费单独设置。 | | `refund` | 退款和退回存款，手续费单独设置。每笔操作的最大值沿用提现的；最小值不做校验。 | | `internalTransfer` | 账户间转账。 | | `dailyWithdraw` | Pix 转出的每日上限，以及今天已用的额度。 | | `dailyInternalTransfer` | 同上，适用于账户间转账。 | | `infraction` | MED 争议不成立时收取的分析费，以及分析期间被争议金额是否从可用余额中扣出（`blocksBalance`）。 | 每项操作中，`enabled` 表示是否开放，`ticketMin` 和 `ticketMax` 是最小和最大金额，手续费由固定部分（`feeFixed`）和百分比部分（`feePercentage`）相加。 在每日上限中，`limit: null` 表示无上限，`0` 表示全部阻止。有上限时，`used` 按巴西利亚时间统计当天，包括仍在处理中的操作；无上限时为 `0`。 ## 指标 [#指标] `GET /transactions/metrics?dateFrom=2026-09-01&dateTo=2026-09-30` 不传 `dateFrom` 和 `dateTo` 时，期间为最近 30 天。 * 收款按创建日期计入：9 月的转化率是 9 月创建的收款中已支付的比例，即使付款发生在 10 月。 * `rails` 中账户的每种支付方式各一项。没有指标的方式为 `available: false`，不带数字；期间内没有收款的 Pix 各项数字为零。 * 比率（`conversionRate`、`refundRate`、`disputeRate`）采用与 `feePercentage` 相同的格式，没有基数时为 `null`。 * `withdrawals` 合计未失败的提现，含手续费。`deposits` 合计无收款单的入账 Pix。`pixInflow` 合计已支付的收款和存款。 所有字段见[查询指标](/docs/conta-digital/endpoints/account/get_metrics)。