> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Feed bancário contínuo para contabilidade: saldos e transações

> Crie um feed diário de saldos e transações por cliente com a Didit: ligação contínua, webhooks, cursor, reposição e paragem.

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](https://docs.didit.me/pt/core-technology/bank-verification/quickstart.md#passo-1-crie-uma-chave-de-api-com-a-permissão-dados-bancários).
* Um destino de webhook que recebe os eventos `bank.*`. Consulte [Webhooks bancários](https://docs.didit.me/pt/core-technology/bank-verification/webhooks.md).
* 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.

## Passo 1: crie uma ligação com acesso contínuo

```bash theme={null}
curl -X POST https://verification.didit.me/v3/bank/links/ \
  -H "x-api-key: $DIDIT_API_KEY" -H "content-type: application/json" \
  -d '{
    "access": "ongoing",
    "country": "ESP",
    "segment": "business",
    "data": ["accounts", "balances", "transactions"],
    "history_from": "2026-01-01",
    "consent_days": 180,
    "ownership": { "compare": "none" },
    "end_user": { "reference": "client-7731", "email": "ana@example.com" },
    "redirect_url": "http://localhost:3000/bank/return",
    "vendor_data": "client-7731"
  }'
```

* `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](https://docs.didit.me/pt/integration/bank-link/hosted-link.md) e devolva-o ao seu produto com um [URL de redirecionamento](https://docs.didit.me/pt/integration/bank-link/return-to-your-site.md).

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:

```bash theme={null}
curl https://verification.didit.me/v3/bank/links/$LINK_ID/ -H "x-api-key: $DIDIT_API_KEY"
```

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:

```bash theme={null}
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/?limit=500" \
  -H "x-api-key: $DIDIT_API_KEY"
```

```python theme={null}
cursor, page_token = stored_cursor or "", None
while True:
    params = {"limit": 500, "page_token": page_token} if page_token else {"cursor": cursor, "limit": 500}
    page = get(f"/v3/bank/connections/{connection_id}/transactions/sync/", params)
    if page["reset"] and not page_token:
        wipe_local_copy(connection_id)       # replace, never append
    apply(page["added"], page["modified"], page["removed"])
    if not page["has_more"]:
        store_cursor(connection_id, page["next_cursor"])
        break
    page_token = page["next_page_token"]
```

* 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](https://docs.didit.me/pt/use-cases/refresh-bank-data-on-demand.md).

## 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`](https://docs.didit.me/pt/standalone-apis/bank-connection-renew) 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](https://docs.didit.me/pt/use-cases/renew-bank-consent.md).

## Passo 7: parar o acesso e eliminar

* O cliente sai do seu produto: chame [`revoke_connection`](https://docs.didit.me/pt/standalone-apis/bank-connection-revoke) para parar a leitura de imediato, ou [`delete_connection`](https://docs.didit.me/pt/standalone-apis/bank-connection-delete) 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](https://docs.didit.me/pt/getting-started/bank-verification-pricing.md#dados-bancários-e-acesso-contínuo).

## Lista de verificação

* [ ] Uma ligação por cliente e banco, guardada com o respetivo cursor e o fim do consentimento.
* [ ] Manipulador de webhooks idempotente, com o ID do evento como chave.
* [ ] `reset: true` substitui a sua cópia, nunca acrescenta.
* [ ] `removed` tratado, com o respetivo motivo.
* [ ] Lembretes de consentimento ligados ao seu próprio aviso ao cliente.
* [ ] `bank.connection.revoked` interrompe o fluxo de dados.
* [ ] O plano sandbox em [Sandbox](https://docs.didit.me/pt/core-technology/bank-verification/sandbox.md#um-bom-plano-de-testes) passa.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.