> ## 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 bancario continuo per la contabilità: saldi e transazioni

> Crea un feed giornaliero di saldi e transazioni per ogni cliente con Didit: collegamento continuo, webhook, cursore, reset, fine consenso, stop.

Un flusso bancario continuo fornisce a un prodotto di contabilità o tenuta dei libri contabili i saldi e le transazioni dei conti bancari di ogni cliente, ogni giorno, senza che il cliente debba effettuare di nuovo l'accesso.

Con Didit crei un link con accesso continuo, ricevi webhook quando arrivano nuovi dati, leggi solo ciò che è cambiato tramite un cursore, monitori la scadenza del consenso e interrompi o elimini l'accesso quando il cliente lascia il servizio.

Questa guida ti accompagna dall'inizio fino a un flusso giornaliero per un singolo cliente.
Lo stesso codice funziona per ogni cliente: una connessione per ogni cliente e banca.

## Cosa ti serve

* Una chiave API con l'autorizzazione per i dati bancari, per la tua applicazione sandbox. Consulta la [guida rapida](https://docs.didit.me/it/core-technology/bank-verification/quickstart.md#passaggio-1-crea-una-chiave-api-con-l’autorizzazione-bank-data).
* Una destinazione webhook che riceve gli eventi `bank.*`. Consulta [Webhook bancari](https://docs.didit.me/it/core-technology/bank-verification/webhooks.md).
* Una tabella nel tuo database per l'ID di connessione di ciascun cliente, il cursore del feed delle modifiche e la fine del consenso.

## Passaggio 1: crea un link con accesso continuo

```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` mantiene l'accesso aperto fino alla fine del consenso. `consent_days` è una richiesta: la banca decide la data effettiva, che viene mostrata sulla connessione.
* `history_from` chiede lo storico a partire da una data, per esempio dall'inizio dell'anno. In alternativa, se preferisci, usa `history_days` (da 1 a 365), mai entrambi. La banca potrebbe fornire meno dati: ogni conto riporta `history_coverage`.
* `ownership.compare: none` salta il confronto del titolare, quindi non serve un'identità di riferimento. Usa `business` per confrontare il titolare con un'azienda verificata in Didit.
* `end_user.reference` è il tuo identificativo del cliente. È ricercabile e permette a Didit di riconoscere lo stesso cliente quando collega di nuovo gli stessi conti.
* Invia il cliente alla [pagina di verifica ospitata](https://docs.didit.me/it/integration/bank-link/hosted-link.md) e riportalo al tuo prodotto con un [URL di reindirizzamento](https://docs.didit.me/it/integration/bank-link/return-to-your-site.md).

Salva l'`id` del link insieme ai dati del cliente.

## Passaggio 2: attendere la connessione

Quando il client completa il flusso, arriva `bank.link.completed` con il `connection_id`.
Confermalo, perché il browser non è mai considerato attendibile:

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

Salva il `connection_id` e attendi `bank.connection.created`: a quel punto conti, saldi e transazioni recenti sono leggibili (`sync.initial_status` vale `succeeded` oppure `partial`).
`bank.connection.history_complete` arriva quando il recupero dello storico è terminato.
Per ogni conto, `history_coverage.oldest_booking_date` indica quanto indietro nel tempo la banca ha effettivamente fornito i dati.

## Passaggio 3: carica la prima copia

Un cursore vuoto restituisce tutte le transazioni correnti come `added` con `reset: true`.
Scorri le pagine e salva il cursore solo alla fine:

```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"]
```

* La prima lettura è un'istantanea reale: restituisce ogni transazione che la connessione aveva all'inizio della lettura, ciascuna una sola volta come `added`, nel suo stato attuale, anche se una sincronizzazione viene eseguita mentre scorri le pagine.
* Le modifiche apportate mentre scorri le pagine arrivano nella lettura successiva da `next_cursor`: una transazione già ricevuta torna come `modified`, e una nuova come `added`.
* Salva `next_cursor` solo dopo una risposta con `has_more: false`.
* Se la paginazione si interrompe a metà, ricomincia dal cursore salvato.
* Leggi i saldi con `GET /v3/bank/accounts/{account_id}/balances/`.

## Passaggio 4: resta aggiornato su ogni webhook

Didit sincronizza automaticamente ogni connessione continuativa attiva da una a quattro volte al giorno, a seconda della banca (`sync.frequency_per_day`).
Quando una sincronizzazione salva modifiche, `bank.data.updated` arriva con `connection_id`, `account_ids` e i conteggi.
Chiama il feed delle modifiche con il cursore salvato:

* `added` sono le nuove transazioni, comprese quelle in attesa.
* `modified` sono le transazioni modificate, nel loro stato attuale. Applica ciascuna come upsert tramite `id`: quella che possiedi già viene aggiornata, e quella che non possiedi ancora viene aggiunta.
* `removed` contengono un `reason`. Ignora un `id` che non possiedi. Quando una transazione in attesa viene contabilizzata, viene restituita in `removed` con `pending_booked` e quella contabilizzata arriva in `added`.

Usa l'`id` della transazione come chiave: resta lo stesso tra letture, sincronizzazioni e rinnovi.
Controlla `identity_quality`: con `derived`, una correzione della banca può comparire come un elemento `removed` e uno `added`.
Le letture non vengono mai fatturate, ma i dati cambiano solo quando viene eseguita una sincronizzazione, quindi una lettura per ogni webhook è sufficiente.
Per recuperare i dati prima, usa Sync Now: [Aggiornare i dati bancari su richiesta](https://docs.didit.me/it/use-cases/refresh-bank-data-on-demand.md).

## Step 5: gestire il reset

Un cursore più vecchio della finestra di replay riceve la risposta `410 cursor_expired` con `bootstrap: true`.
Il registro delle modifiche può essere riprodotto per 90 giorni, quindi questo caso è raro per un processo giornaliero.
Ricomincia da un cursore vuoto e sostituisci la tua copia con il risultato, invece di aggiungerlo a essa.
Ogni lettura da un cursore vuoto include `reset: true`, quindi lo stesso percorso di codice gestisce sia una nuova connessione sia un cursore scaduto.

## Passaggio 6: verifica la scadenza del consenso

Il consenso ha una data di scadenza: `consent.expires_at`.
Didit invia `bank.connection.consent_expiring` 14, 7 e 1 giorno prima della scadenza.

Chiama [`renew_connection`](https://docs.didit.me/it/standalone-apis/bank-connection-renew) quando vuoi rinnovare: risponde `409 renewal_not_needed` finché non mancano 30 giorni.
La pagina in cui il cliente completa un rinnovo non è ancora disponibile.

Se il cliente lascia scadere il consenso, la connessione passa a `renewal_required`: puoi comunque leggere i dati sincronizzati.
I dettagli sono in [Rinnova un consenso bancario](https://docs.didit.me/it/use-cases/renew-bank-consent.md).

## Passaggio 7: interrompere l'accesso ed eliminare

* Il cliente lascia il tuo prodotto: chiama [`revoke_connection`](https://docs.didit.me/it/standalone-apis/bank-connection-revoke) per interrompere subito la lettura, oppure [`delete_connection`](https://docs.didit.me/it/standalone-apis/bank-connection-delete) per interrompere e eliminare i dati memorizzati.
* Il cliente smette di condividere i dati con la banca: `bank.connection.revoked` arriva con `ended_by`. Interrompi il flusso di dati per quella connessione.

## Prezzi

L'accesso continuo viene fatturato per connessione attiva al mese.
Il prezzo include tutti i conti della connessione, i saldi, le transazioni, fino a 365 giorni di storico dove la banca lo fornisce, le sincronizzazioni automatiche, le sincronizzazioni in tempo reale entro i limiti della banca, i rinnovi, i webhook e tutte le letture.
Un link che nessuno completa è gratuito, e lo sono anche le connessioni con stato `renewal_required`, `paused` o `revoked`.
Vedi [prezzi](https://docs.didit.me/it/getting-started/bank-verification-pricing.md#dati-bancari-e-accesso-continuativo).

## Checklist

* [ ] Una connessione per cliente e banca, memorizzata con il suo cursore e la scadenza del consenso.
* [ ] Gestore dei webhook idempotente, con chiave sull'id dell'evento.
* [ ] `reset: true` sostituisce la tua copia, non l'accoda mai.
* [ ] `removed` gestito, con il relativo motivo.
* [ ] Promemoria sul consenso collegati alla tua comunicazione al cliente.
* [ ] `bank.connection.revoked` interrompe il flusso.
* [ ] Il piano sandbox in [Sandbox](https://docs.didit.me/it/core-technology/bank-verification/sandbox.md#un-buon-piano-di-test) supera il test.


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