> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Saldo, saldo diário e encerramento

Saldo atual, série de saldos diários e encerramento de uma conta, no host
`https://tenant.api.corpx.com`. Todas as chamadas levam
`Authorization: Bearer {token}` e `X-Tenant-Id`.

## Saldo

`GET /v1/accounts/{accountId}/balance`

```bash
curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/balance" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"
```

```json
{
  "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
  "total": 18254.17,
  "locked": 500.00,
  "available": 17754.17,
  "currency": "BRL",
  "updatedAt": "2026-02-05T22:00:00Z"
}
```

`available` é o que a conta pode enviar. `locked` é o total retido (por
exemplo, uma retenção de [MED](/baas/guias/pagar/med)); a resposta não lista
cada retenção. `includeLocks` é aceito por compatibilidade e não tem efeito.

## Saldo diário

`GET /v1/accounts/{accountId}/daily-balance?startDate=2026-06-04&endDate=2026-06-05`

Devolve, por dia, a abertura (total / bloqueado / disponível) e os fluxos do
dia, em horário de Brasília. Janela máxima de 30 dias; sem datas, vale os
últimos 30 dias. Só há fechamentos a partir de 2026-06-04 (`cutoffDate`).

```json
{
  "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
  "startDate": "2026-06-04",
  "endDate": "2026-06-04",
  "cutoffDate": "2026-06-04",
  "timezone": "America/Sao_Paulo",
  "items": [
    {
      "date": "2026-06-04",
      "openTotalBalance": 10000.00,
      "openBlockedBalance": 0,
      "openAvailableBalance": 10000.00,
      "pixIn": 1200.00,
      "pixOut": 300.00,
      "pixBillingOut": 1.50,
      "tedIn": 0,
      "tedOut": 0,
      "tedBillingOut": 0,
      "internalTransferIn": 0,
      "internalTransferOut": 0,
      "internalTransferBillingOut": 0,
      "bankSlipOut": 0,
      "stablecoinBurn": 0,
      "stablecoinMint": 0,
      "cardSettlementIn": 845.30,
      "cardSettlementOut": 0,
      "currency": "BRL"
    }
  ],
  "fetchedAt": "2026-06-05T12:00:00Z"
}
```

Os fluxos vêm somados por tipo, sempre presentes e com `0` quando não houve
movimento:

| Tipo                  | Entradas                                           | Saídas                | Tarifas                      |
| --------------------- | -------------------------------------------------- | --------------------- | ---------------------------- |
| Pix                   | `pixIn`                                            | `pixOut`              | `pixBillingOut`              |
| TED                   | `tedIn`                                            | `tedOut`              | `tedBillingOut`              |
| Transferência interna | `internalTransferIn`                               | `internalTransferOut` | `internalTransferBillingOut` |
| Boleto                | —                                                  | `bankSlipOut`         | —                            |
| BRMT                  | `stablecoinMint`                                   | `stablecoinBurn`      | —                            |
| Liquidação de cartões | `cardSettlementIn` (débito, crédito e antecipação) | `cardSettlementOut`   | —                            |

A abertura de um dia é a abertura do dia anterior mais as entradas, menos as
saídas e as tarifas daquele dia.

## Encerrar a conta

`POST /v1/accounts/{accountId}/close`

Tira o acesso do seu tenant à conta. Pessoas precisam do papel
`tenant_manager` ou `admin`; credenciais, do escopo `accounts.close` (o
legado `api2/write` também passa). Mande um `Idempotency-Key` para poder
repetir a chamada com segurança.

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/close" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Idempotency-Key: close-2e6b725b-001"
```

```json
{
  "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
  "message": "Este tenant perdeu o acesso à conta. Ela será encerrada em breve se nenhum outro tenant estiver usando."
}
```

A resposta `200` é a mesma quando outro tenant da CorpX ainda opera a conta
e quando o seu é o último. A conta não é apagada: passa a `status=closed`.
Repetir o pedido numa conta já encerrada no seu tenant devolve o mesmo `200`,
sem novo pedido de encerramento.

**Quando a conta é só sua**, o encerramento é pedido ao liquidante, que só
aceita conta zerada: sem saldo disponível e sem saldo bloqueado. O saldo do
liquidante é conferido antes:

| Situação                                                                  | Resposta                                                                                        | O que fazer                                                            |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Saldo disponível diferente de zero                                        | **422** [`account_has_balance`](/baas/guias/referencia/erros#account_has_balance)               | Retire o saldo e repita.                                               |
| Disponível zerado, mas com saldo bloqueado (por exemplo, retenção de MED) | **422** [`account_has_locked_balance`](/baas/guias/referencia/erros#account_has_locked_balance) | Espere a liberação do bloqueio e repita.                               |
| Saldo zerado                                                              | **200**                                                                                         | O encerramento é pedido ao liquidante e o acesso sai na mesma chamada. |

Nos dois `422` a conta continua ativa e o corpo traz o saldo do liquidante:

```json
{
  "errorCode": "account_has_locked_balance",
  "message": "para cancelar a conta no liquidante é preciso liberar o saldo bloqueado antes",
  "errorReason": "para cancelar a conta no liquidante é preciso liberar o saldo bloqueado antes",
  "balance": {
    "total": 50.00,
    "available": 0,
    "locked": 50.00,
    "currency": "BRL"
  }
}
```

A conta bancária em si é encerrada quando o liquidante processa o pedido; o
`200` não diz quando.

Outros erros:

| Status | Código                                      | Quando                                                                                        |
| ------ | ------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 404    | `account_not_found`                         | Conta inexistente, de outro tenant ou `suspended`. Nunca `403 tenant_mismatch`.               |
| 403    | `forbidden`                                 | Pessoa sem papel `tenant_manager` ou `admin` (um `viewer`, por exemplo).                      |
| 403    | `insufficient_scope`                        | Credencial sem o escopo `accounts.close`.                                                     |
| 409    | `request_in_progress`                       | O mesmo `Idempotency-Key` ainda está sendo processado.                                        |
| 503    | `banking_unavailable` / `email_unavailable` | Liquidante ou envio do pedido indisponível. A conta continua ativa; tente de novo mais tarde. |