Um feed bancário contínuo fornece a um produto de contabilidade ou de escrituração os saldos e as transações das contas bancárias de cada cliente todos os dias, sem que o cliente tenha de voltar a iniciar sessão.
Com a Didit, cria uma ligação com acesso contínuo, recebe webhooks quando chegam novos dados, lê apenas o que mudou com um cursor, monitoriza o momento em que o consentimento termina e interrompe ou elimina o acesso quando o cliente sai.
Este guia leva-o do zero até um feed diário para um cliente.
O mesmo código funciona para todos os clientes: uma ligação por cliente e por banco.
O que precisa
- Uma chave de API com a permissão de dados bancários, para a sua aplicação sandbox. Consulte o início rápido.
- Um destino de webhook que recebe os eventos
bank.*. Consulte Webhooks bancários.
- Uma tabela na sua base de dados para o ID da ligação, o cursor do feed de alterações e o fim do consentimento de cada cliente.
access: ongoing mantém o acesso aberto até o consentimento terminar. consent_days é um pedido: o banco decide a data real, que aparece na ligação.
history_from pede o histórico a partir de uma data, por exemplo o início do ano. Em alternativa, use history_days (de 1 a 365), se preferir; nunca os dois. O banco pode entregar menos: cada conta indica o history_coverage.
ownership.compare: none ignora a comparação do titular, por isso não é necessária nenhuma identidade de referência. Use business para comparar o titular com uma empresa verificada na Didit.
end_user.reference é o seu id para o cliente. É pesquisável e permite à Didit reconhecer o mesmo cliente quando ligar novamente as mesmas contas.
- Envie o cliente para a página de verificação alojada e devolva-o ao seu produto com um URL de redirecionamento.
Guarde o id da ligação junto do cliente.
Passo 2: aguarde a ligação
Quando o cliente terminar, chega bank.link.completed com o connection_id.
Confirme-o, uma vez que o navegador nunca é considerado fiável:
Guarde o connection_id e aguarde bank.connection.created: as contas, os saldos e as transações recentes ficam então disponíveis para leitura (sync.initial_status é succeeded ou partial).
bank.connection.history_complete é recebido quando termina o preenchimento retroativo do histórico.
Para cada conta, history_coverage.oldest_booking_date indica até que data no passado o banco forneceu efetivamente dados.
Passo 3: carregar a primeira cópia
Um cursor vazio devolve todas as transações atuais como added com reset: true.
Percorra todas as páginas e guarde o cursor apenas no fim:
- A primeira leitura é um instantâneo fiel: devolve cada transação que a ligação tinha no início da leitura, exatamente uma vez como
added, no estado atual, mesmo que seja executada uma sincronização enquanto percorre as páginas.
- As alterações feitas durante a paginação chegam na leitura seguinte a partir de
next_cursor: uma transação que já recebeu volta a ser devolvida como modified, e uma nova é devolvida como added.
- Guarde
next_cursor apenas depois de uma resposta com has_more: false.
- Se a paginação falhar a meio, recomece a partir do cursor que guardou.
- Consulte os saldos com
GET /v3/bank/accounts/{account_id}/balances/.
Passo 4: mantenha-se atualizado através de cada webhook
A Didit sincroniza automaticamente cada ligação bancária ativa entre uma e quatro vezes por dia, consoante o banco (sync.frequency_per_day).
Quando uma sincronização guarda alterações, o evento bank.data.updated é recebido com o connection_id, os account_ids e as contagens.
Chame o fluxo de alterações com o cursor guardado:
added são as novas transações, incluindo as pendentes.
modified são as transações que mudaram, no seu estado atual. Aplique cada uma como uma operação de inserção ou atualização pelo id: se já tiver essa transação, é atualizada; se ainda não a tiver, é adicionada.
removed incluem um reason. Ignore um id que não tenha. Quando uma transação pendente é lançada, sai em removed com pending_booked e a transação lançada chega em added.
Use o id da transação como chave: mantém-se igual em todas as leituras, sincronizações e renovações.
Verifique o identity_quality: com derived, uma correção do banco pode aparecer como um removed e um added.
As leituras nunca são faturadas, mas os dados só mudam quando corre uma sincronização, por isso uma leitura por webhook é suficiente.
Para obter os dados mais cedo, use o Sync Now: Atualizar dados bancários a pedido.
Passo 5: tratar a reposição
Um cursor mais antigo do que a janela de reprodução responde com 410 cursor_expired e bootstrap: true.
O registo de alterações pode ser reproduzido durante 90 dias, por isso isto é raro numa tarefa diária.
Recomece a partir de um cursor vazio e substitua a sua cópia pelo resultado, em vez de lhe acrescentar dados.
Cada leitura a partir de um cursor vazio inclui reset: true, por isso o mesmo caminho de código trata uma nova ligação e um cursor expirado.
Passo 6: acompanhe o fim do consentimento
O consentimento tem uma data de fim: consent.expires_at.
A Didit envia bank.connection.consent_expiring 14, 7 e 1 dia antes dessa data.
Chame renew_connection quando quiser renovar: responde com 409 renewal_not_needed até faltarem 30 dias.
A página onde o cliente conclui uma renovação ainda não está disponível.
Se o cliente deixar expirar o consentimento, a ligação fica renewal_required: continua a poder ler o que foi sincronizado.
Os detalhes estão em Renovar um consentimento bancário.
Passo 7: parar o acesso e eliminar
- O cliente sai do seu produto: chame
revoke_connection para parar a leitura de imediato, ou delete_connection para parar e eliminar os dados guardados.
- O cliente deixa de partilhar no banco:
bank.connection.revoked é recebido com ended_by. Pare o fluxo de dados dessa ligação.
Preço
O acesso contínuo é cobrado por ligação ativa e por mês.
O preço inclui todas as contas da ligação, saldos, transações, até 365 dias de histórico quando o banco o disponibiliza, as sincronizações automáticas, as sincronizações em tempo real dentro dos limites do banco, as renovações, os webhooks e todas as leituras.
Uma ligação que ninguém conclui é gratuita, e o mesmo acontece com as ligações em renewal_required, paused e revoked.
Consulte os preços.
Lista de verificação
Última modificação em 22 de novembro de 2026