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.
- Una destinazione webhook che riceve gli eventi
bank.*. Consulta Webhook bancari.
- 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
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 e riportalo al tuo prodotto con un URL di reindirizzamento.
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:
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:
- 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.
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 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.
Passaggio 7: interrompere l’accesso ed eliminare
- Il cliente lascia il tuo prodotto: chiama
revoke_connection per interrompere subito la lettura, oppure delete_connection 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.
Checklist
Ultima modifica il 22 novembre 2026