Pular para o conteúdo principal
Um feed bancário contínuo fornece a um produto de contabilidade ou escrituração os saldos e as transações das contas bancárias de cada cliente todos os dias, sem que o cliente precise fazer login novamente. Com a Didit, você cria um link com acesso contínuo, recebe webhooks quando novos dados chegam, lê apenas o que mudou usando um cursor, acompanha quando o consentimento termina e interrompe ou exclui o acesso quando o cliente deixa de ser cliente. Este guia leva você do zero a um feed diário para um cliente. O mesmo código roda para todos os clientes: uma conexão por cliente e banco.

O que você precisa

  • Uma chave de API com a permissão de dados bancários, para a sua aplicação de sandbox. Veja o guia de início rápido.
  • Um destino de webhook que receba os eventos bank.*. Veja Webhooks bancários.
  • Uma tabela no seu banco de dados para o ID da conexão de cada cliente, o cursor do fluxo de alterações e a data de término do consentimento.
  • access: ongoing mantém o acesso aberto até o fim do consentimento. consent_days é um pedido: o banco define a data real, que aparece na conexão.
  • history_from solicita o histórico a partir de uma data, por exemplo, o início do ano. Se preferir, use history_days (de 1 a 365), mas nunca os dois. O banco pode entregar menos: cada conta informa seu history_coverage.
  • ownership.compare: none ignora a comparação do titular, então nenhuma identidade de referência é necessária. Use business para comparar o titular com uma empresa verificada na Didit.
  • end_user.reference é o seu identificador do cliente. Ele é pesquisável e permite que a Didit reconheça o mesmo cliente ao conectar as mesmas contas novamente.
  • Envie o cliente para a página de verificação hospedada e devolva-o ao seu produto por meio de uma URL de redirecionamento.
Armazene o id do link junto ao cliente.

Etapa 2: aguarde a conexão

Quando o cliente concluir, bank.link.completed chega com o connection_id. Confirme-o, já que o navegador nunca é confiável:
Salve o connection_id e aguarde bank.connection.created: as contas, os saldos e as transações recentes podem ser consultados a partir daí (sync.initial_status é succeeded ou partial). bank.connection.history_complete chega quando a carga retroativa do histórico termina. Para cada conta, history_coverage.oldest_booking_date indica até que data o banco realmente entregou os dados.

Etapa 3: carregue a primeira cópia

Um cursor vazio retorna todas as transações atuais como added com reset: true. Percorra as páginas e armazene o cursor somente no final:
  • A primeira leitura é um instantâneo verdadeiro: retorna todas as transações que a conexão tinha quando a leitura começou, cada uma exatamente uma vez como added, em seu estado atual, mesmo que uma sincronização ocorra enquanto você percorre as páginas.
  • Alterações feitas durante a paginação chegam na próxima leitura a partir de next_cursor: uma transação que você já recebeu volta como modified, e uma nova, como added.
  • Armazene next_cursor somente após uma resposta com has_more: false.
  • Se a paginação falhar no meio do caminho, reinicie a partir do cursor que você armazenou.
  • Leia os saldos com GET /v3/bank/accounts/{account_id}/balances/.

Passo 4: mantenha-se atualizado com cada webhook

A Didit sincroniza automaticamente todas as conexões contínuas ativas entre uma e quatro vezes por dia, dependendo do banco (sync.frequency_per_day). Quando uma sincronização armazena alterações, bank.data.updated chega com o connection_id, os account_ids e as contagens. Chame o feed de alterações com o cursor armazenado:
  • added são transações novas, incluindo as pendentes.
  • modified são transações que mudaram, no estado atual. Aplique cada uma como um upsert pelo id: se você já tem a transação, ela é atualizada; se ainda não a tem, ela é adicionada.
  • removed traz um reason. Ignore um id que você não tem. Quando uma transação pendente é lançada, ela sai em removed com pending_booked, e a transação lançada chega em added.
Use o id da transação como chave: ele permanece o mesmo entre 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 cobradas, mas os dados só mudam quando uma sincronização é executada, então uma leitura por webhook é suficiente. Para buscar mais cedo, use o Sync Now: Atualize os dados bancários sob demanda.

Etapa 5: lidar com a redefinição

Um cursor mais antigo que a janela de reprodução responde 410 cursor_expired com bootstrap: true. O log de alterações pode ser reproduzido durante 90 dias, então isso é raro para uma tarefa diária. Comece de novo a partir de um cursor vazio e substitua sua cópia pelo resultado, em vez de adicionar dados a ela. Toda leitura a partir de um cursor vazio traz reset: true, então o mesmo caminho de código trata uma nova conexão e um cursor expirado.

Etapa 6: acompanhe o fim do consentimento

O consentimento tem uma data de término: consent.expires_at. A Didit envia bank.connection.consent_expiring 14, 7 e 1 dia antes dela. Chame renew_connection quando quiser renovar: ela responde 409 renewal_not_needed até restarem 30 dias. A página em que o cliente conclui uma renovação ainda não está disponível. Se o cliente deixar o consentimento expirar, a conexão fica com renewal_required: você ainda pode ler o que foi sincronizado. Os detalhes estão em Renovar um consentimento bancário.

Etapa 7: interrompa o acesso e exclua

  • O cliente deixa o seu produto: chame revoke_connection para parar de ler imediatamente, ou delete_connection para parar e excluir os dados armazenados.
  • O cliente deixa de compartilhar no banco: o evento bank.connection.revoked é enviado com ended_by. Interrompa o fluxo de dados dessa conexão.

Preços

O acesso contínuo é cobrado por conexão ativa por mês. O preço inclui todas as contas da conexão, saldos, transações, até 365 dias de histórico quando o banco o fornece, as sincronizações automáticas, as sincronizações ao vivo dentro dos limites do banco, as renovações, os webhooks e todas as leituras. Um link que ninguém conclui é gratuito, assim como as conexões em renewal_required, paused e revoked. Consulte preços.

Checklist

  • Uma conexão por cliente e banco, armazenada com seu cursor e a data de término do consentimento.
  • Manipulador de webhook idempotente, usando o ID do evento como chave.
  • reset: true substitui sua cópia, nunca acrescenta.
  • removed tratado, junto com o motivo.
  • Lembretes de consentimento vinculados à sua própria notificação ao cliente.
  • bank.connection.revoked interrompe o fluxo.
  • O plano de sandbox em Sandbox passa.
Última modificação em 22 de novembro de 2026