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 ciclos de sincronização regulares.
GET /accounts/{id}/balance
{
"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 contaAPI. |
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 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.
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, de modo que ambos os endpoints permanecem consistentes sem esperar pela próxima sincronização. Valores que a instituição não reportou permanecem como a última sincronização os armazenou.
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.
Aviso
Este endpoint está disponível apenas para conectores Open Finance. Chamá-lo em contas não Open Finance retornará um erro.
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 |
404 | Conta não encontrada para o ID fornecido |
429 | Limite de taxa imposto pela instituição financeira -- tente novamente mais tarde |
500 | Erro ao buscar o saldo do conector |
Veja Obter saldo em tempo realAPI na referência da API para mais detalhes.