Saldo e Extrato no OpenFinance — separação das rotas

Status: em vigor desde 12 de agosto de 2026 

Impacto: leitura do campo balance no extrato OpenFinance 

Prazo de depreciação: 02 de dezembro de 2026

Resumo

A atualização contínua dos campos de saldo (balance) dentro do extrato OpenFinance foi desativada em 12 de agosto de 2026.

Saldo e transações passam a ser consultados por duas requisições distintas:

O campo balance continua presente na resposta do extrato até 02 de dezembro de 2026, apenas para transição. Ele não reflete mais o saldo atualizado e deve deixar de ser lido o quanto antes.

Por que a mudança

Na origem (instituições financeiras via OpenFinance), saldo e transações são duas informações distintas e alimentadas de forma diferente.

No início do projeto da API de Open Finance, as duas bases de informações (transações e balanços) vinham bem sincronizadas onde o saldo atual e as transações do extrato chegavam praticamente juntos para nós.

Com o tempo, a rota de saldo evoluiu e ficou muito mais rápida e eficiente, enquanto a rota de transações - utilizada para calcular o balanço - manteve uma latência de atualizações maior, e conforme o tempo vai passando, essa distância vem aumentando.

Ponto importante: não há transações faltando. As transações aparecem, mas apenas levam mais tempo para serem publicadas no extrato do que o saldo leva para ser atualizado. É uma diferença de tempo de propagação, não de dados perdidos.

Recomendação principal

Não faça conciliação de transações usando o saldo instantâneo como referência.

A rota de saldo em tempo real, possui a finalidade exclusivamente de consulta de saldo da conta e, não é recomendada para o fim de conciliação de saldo do extrato.

Não faça conciliação de transações com base no saldo instantâneo. Como as transações têm um tempo maior de publicação, a comparação sempre ficará divergente.

Isso acontece porque, por padrão, os Bancos possuem um SLA maior para atualizar as transações no ecossistema do OpenFinance enquanto a rota de saldo busca uma informação em tempo real.

Nova rota de consulta de saldo

Para consultar o saldo da conta, é necessário disparar uma requisição na nova rota de saldo em tempo real:

Extrato OpenFinance - Documentação Técnica

Limite de requisições e cache de 6 horas

O OpenFinance trabalha com um limite de requisições que consome créditos mensais. Estourar esse limite interrompe o funcionamento da aplicação. Não só a consulta de saldo.

Para proteger isso, a rota de saldo adota o mesmo período de cache/limite já usado no extrato: 6 horas.

Campo nextUpdate

O controle da sincronização é feito pelo campo nextUpdate, retornado na resposta:

nextUpdate — data e hora a partir da qual uma nova consulta buscará um saldo atualizado (horário da consulta + 6 horas de cache).

Como usar:

• Consultas feitas antes de nextUpdate retornam o valor em cache, sem consumir uma nova sincronização na origem.
• Consultas feitas a partir de nextUpdate disparam a busca de um saldo atualizado.
• Agende suas sincronizações por esse campo em vez de por intervalo fixo do seu lado, assim você não desperdiça créditos nem se descola do cache real.

Depreciação do campo balance no extrato

A estrutura abaixo, hoje presente na resposta do extrato, permanece por 90 dias a partir de setembro/2026 e depois será removida:

"balance": {
  "inicial": {
    "date": "2024-10-20",
    "balance": "0"
  },
  "final": {
    "date": "2025-09-17",
    "balance": "0"
  }
}

O prazo existe para que todos consigam adequar a leitura sem quebras indesejadas. Durante o período:

• O campo continua sendo entregue na resposta.
• Ele não é mais atualizado de forma contínua e não deve ser tratado como saldo atual.
• Novos avisos serão enviados conforme o fim do prazo se aproximar.

Sugestão: interrompa a leitura desse campo o quanto antes, sem esperar o fim dos 90 dias.

Checklist de adequação

1. Localizar no seu código todos os pontos que leem balance.inicial e balance.final da resposta do extrato.
2. Trocar esses pontos pela chamada à rota getBalanceRealTimeOpenfinance.
3. Passar a respeitar nextUpdate para agendar a próxima consulta de saldo.
4. Revisar rotinas de conciliação que comparam transações contra saldo instantâneo para remover ou reformular essa comparação.
5. Confirmar que nenhum alerta interno dispara com base na divergência saldo × transações.

Perguntas frequentes

Estão faltando transações no meu extrato? 

Não. Elas têm um tempo maior de publicação do que o saldo. Aguarde a propagação, então a transação aparecerá.

Posso consultar o saldo com mais frequência que 6 horas? 

A resposta virá do cache até nextUpdate. O limite existe para não estourar os créditos mensais do OpenFinance e derrubar a operação.

O que acontece depois dos 90 dias?

O bloco balance deixa de ser retornado no extrato. Quem ainda estiver lendo esse campo terá quebra.

Por que não sincronizar as duas rotas do lado de vocês?

A defasagem é na origem, não na nossa camada. Segurar o saldo até as transações chegarem só pioraria a informação para quem precisa do saldo atual.