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

# Saldo

> Quanto a sua conta tem para usar agora (available) e quanto está separado (reserved).

# Saldo

Responde à pergunta **"quanto eu tenho para usar agora?"**. O saldo é da conta inteira: todos os canais usam o mesmo.

```bash theme={null}
curl "https://api-dev.messagefy.io/api/v1/billing/Balance" -H "API-KEY: acc_..."
```

## Parâmetros

**currency** `string` (default: BRL)

Moeda do saldo (ISO 4217, ex.: `BRL`). Outro formato é recusado com `400`.

**accountId** `uuid`

Só para chaves `org_`: a conta a consultar. Com chave `acc_`, a conta vem da chave e este parâmetro não é necessário.

## Resposta

```json theme={null}
{
  "account": {
    "id": "11111111-1111-1111-1111-111111111111",
    "available": 1250.4300,
    "reserved": 0.0000,
    "currency": "BRL"
  },
  "wallets": []
}
```

Lendo esse exemplo: a conta tem **R\$ 1.250,43** para usar agora, e nada está separado.

| Campo | O que é | Exemplo |
| - | - | - |
| `account.id` | A sua conta | `11111111-...` |
| `account.available` | O que pode ser usado agora. **Negativo** = valor a receber: os envios ficam bloqueados até um crédito cobrir a diferença (mensagens recebidas continuam chegando) | `1250.4300` = R\$ 1.250,43 |
| `account.reserved` | Separado para envios em andamento: ainda não pode ser usado. Hoje sempre `0` | `0.0000` |
| `account.currency` | Moeda dos valores (ISO 4217) | `BRL` = reais |
| `wallets` | Reservado para uma próxima versão (o saldo separado por carteira). Hoje sempre `[]` | `[]` |

Conta que ainda não tem saldo devolve `available: 0`, não erro.

> [!TIP]
>
> Para mostrar o saldo numa tela, use `account.available`. Para saber se dá para enviar agora, confira se ele é maior
> que zero.

## Erros

| HTTP | `errorCode` | Quando |
| - | - | - |
| `400` | `CURRENCY_INVALID` | `currency` fora do formato ISO 4217 (ex.: `reais`) |
| `401` | — | Chave inválida ou ausente |
| `404` | `ACCOUNT_NOT_FOUND` | Chave `org_` com `accountId` de outra *Organization* |
| `503` | `BILLING_UNAVAILABLE` | Serviço indisponível; tente de novo em instantes |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.