# Saldo em Tempo Real

O endpoint de saldo em tempo real busca o saldo da conta diretamente da instituição financeira sem acionar uma sincronização completa de itens. Isso é útil quando você precisa de informações de saldo atualizadas entre os ciclos de sincronização regulares.

```
GET /accounts/{id}/balance
```

<Callout variant="warning" title="Chame a partir do seu backend com sua chave da API">
Este endpoint aceita apenas sua chave da API (`X-API-KEY` de `POST /auth`). Um Connect Token `accessToken`, aquele que você entrega ao Pluggy Connect, é rejeitado com `403 FORBIDDEN_INSUFFICIENT_PERMISSIONS`, porque ele alcança a instituição em tempo real em nome da sua aplicação.
</Callout>

```json
{
  "balance": 1500.50,
  "blockedBalance": 0,
  "automaticallyInvestedBalance": 200,
  "closingBalance": 1500.50,
  "currencyCode": "BRL",
  "updateDateTime": "2024-01-15T10:30:00Z"
}
```

| Campo | Descrição |
|-------|-------------|
| `balance` | Saldo disponível da conta. Mesmo valor que `balance` no [recurso da conta](/reference/accounts-retrieve). |
| `blockedBalance` | Valor atualmente bloqueado ou retido na conta. Presente apenas quando a instituição o reporta. |
| `automaticallyInvestedBalance` | Valor mantido na instalação de investimento automático da conta. Presente apenas quando a instituição o reporta. |
| `closingBalance` | Saldo contábil da conta: `balance` mais `blockedBalance`. Mesmo valor que `bankData.closingBalance` no recurso da conta. Presente apenas quando a instituição o reporta. |
| `currencyCode` | Moeda dos valores acima. |
| `updateDateTime` | Quando a instituição atualizou pela última vez o saldo. |

O valor de `balance` retornado por este endpoint é calculado usando a mesma lógica que uma execução completa de itens, incluindo a regra do Itaú e do Banco do Brasil para valores automaticamente investidos. A única exceção é o ajuste de cheque especial: uma execução completa retorna `balance` como o negativo do cheque especial utilizado quando a instituição reporta zero e o cheque especial está em uso, e este endpoint não faz isso. Veja [Saldos de contas bancárias no Open Finance](/docs/products/accounts#bank-account-balances-on-open-finance).

Quando você chama este endpoint, o recurso da conta é atualizado com o que a instituição respondeu: `balance`, e, quando reportado, `bankData.closingBalance` e `bankData.automaticallyInvestedBalance`. Qualquer solicitação subsequente `GET /accounts/{id}` reflete os valores buscados pela chamada de saldo em tempo real, então ambos os endpoints permanecem consistentes sem esperar pela próxima sincronização. Valores que a instituição não reportou são deixados como a última sincronização os armazenou.

<Callout variant="info" title="Campos opcionais">
`blockedBalance`, `automaticallyInvestedBalance` e `closingBalance` são omitidos da resposta quando a instituição não os reporta. Trate-os como opcionais na sua integração.
</Callout>

<Callout variant="warning" title="Aviso">
Este endpoint está disponível apenas para **conectores Open Finance**. Chamá-lo em contas que não são Open Finance retornará um erro.
</Callout>

**Limitação de taxa:** O limite de taxa para este endpoint é **compartilhado com a execução completa de itens**. Solicitações ao endpoint de saldo em tempo real e sincronizações de itens contam para a mesma cota de limite de taxa imposta pela instituição financeira. Se a instituição limitar a taxa da solicitação, você receberá uma resposta `429`.

| Código de Resposta | Descrição |
|--------------------|-------------|
| `200` | Saldo buscado e conta atualizada |
| `400` | A instituição rejeitou a solicitação de saldo como inválida (`BALANCE_INVALID_REQUEST`) |
| `403` | A instituição negou acesso ao saldo (`BALANCE_CONSENT_ERROR`): o consentimento pode ter expirado, sido revogado ou estar faltando a permissão necessária, e o usuário pode precisar reconectar o item. Também retornado quando a solicitação usa um Connect Token em vez da sua chave da API |
| `404` | Nenhuma conta com o ID fornecido para sua aplicação (`ACCOUNT_NOT_FOUND`), ou a instituição não tem saldo para a conta (`BALANCE_NOT_FOUND`) |
| `429` | Limite de taxa atingido pela instituição financeira (`BALANCE_OPEN_FINANCE_RATE_LIMIT`) -- tente novamente mais tarde |
| `500` | Erro ao buscar o saldo do conector (`BALANCE_FETCH_ERROR`) |
| `502` | A instituição está temporariamente indisponível (`BALANCE_CONNECTOR_UNAVAILABLE`) -- tente novamente mais tarde |
| `503` | A instituição atingiu seu limite global de solicitações Open Finance e está temporariamente não respondendo (`BALANCE_INSTITUTION_RATE_LIMITED`). O limite cobre todo o tráfego que a instituição recebe, não sua aplicação -- tente novamente mais tarde com backoff |

Veja [Códigos de Erro](/reference/error-codes#real-time-balance) para as mensagens.

Veja [Obter saldo em tempo real](/reference/account-balance-get) na referência da API para mais detalhes.