Procurando a documentação anterior?Acesse v1.docs.pluggy.ai
PluggyDocs

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.

Ver como Markdown

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

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.

json
{
  "balance": 1500.50,
  "blockedBalance": 0,
  "automaticallyInvestedBalance": 200,
  "closingBalance": 1500.50,
  "currencyCode": "BRL",
  "updateDateTime": "2024-01-15T10:30:00Z"
}
CampoDescrição
balanceSaldo disponível da conta. Mesmo valor que balance no recurso da contaAPI.
blockedBalanceValor atualmente bloqueado ou retido na conta. Presente apenas quando a instituição o reporta.
automaticallyInvestedBalanceValor mantido na instalação de investimento automático da conta. Presente apenas quando a instituição o reporta.
closingBalanceSaldo contábil da conta: balance mais blockedBalance. Mesmo valor que bankData.closingBalance no recurso da conta. Presente apenas quando a instituição o reporta.
currencyCodeMoeda dos valores acima.
updateDateTimeQuando 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.

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.

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 que não sã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 RespostaDescrição
200Saldo buscado e conta atualizada
400A instituição rejeitou a solicitação de saldo como inválida (BALANCE_INVALID_REQUEST)
403A 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
404Nenhuma 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)
429Limite de taxa atingido pela instituição financeira (BALANCE_OPEN_FINANCE_RATE_LIMIT) -- tente novamente mais tarde
500Erro ao buscar o saldo do conector (BALANCE_FETCH_ERROR)
502A instituição está temporariamente indisponível (BALANCE_CONNECTOR_UNAVAILABLE) -- tente novamente mais tarde
503A 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 ErroAPI para as mensagens.

Veja Obter saldo em tempo realAPI na referência da API para mais detalhes.

Esta página foi útil?