Vai al contenuto principale
L’API dei dati bancari di Didit memorizza i conti, i saldi e le transazioni di ogni connessione e li restituisce tramite endpoint di lettura con paginazione (cursor sulle liste, page_token sulle letture delle transazioni). Gli importi sono stringhe decimali con una currency separata conforme allo standard ISO 4217; le date seguono lo standard ISO 8601 e i paesi sono indicati in formato ISO alpha-3. Le operazioni di lettura non vengono mai fatturate.

Conti

GET /v3/bank/connections/{id}/accounts/ elenca i conti di una connessione, e GET /v3/bank/accounts/{account_id}/ ne restituisce uno. Usa account_ref per riconoscere un conto bancario quando una persona lo connette di nuovo, e id per tutto ciò che riguarda una singola connessione.

Saldi

GET /v3/bank/accounts/{account_id}/balances/ restituisce i saldi con tipo e le rispettive date di riferimento.
type può essere booked, available o expected, mentre iso_type contiene il codice ISO 20022 della banca, quando la banca ne fornisce uno.

Transazioni

GET /v3/bank/accounts/{account_id}/transactions/ legge un intervallo di date. Accetta date_from e date_to (date di calendario come le riporta la banca, estremi inclusi), status (booked o pending, entrambi per impostazione predefinita), limit (fino a 500) e page_token. Ordina per effective_date in ordine decrescente, poi per id.
  • id è assegnato da Didit e memorizzato alla prima rilevazione. Lo stesso movimento mantiene il proprio id nelle letture, nelle sincronizzazioni e nei rinnovi.
  • identity_quality indica quanto è forte questa garanzia. bank_reference e route_id sono stabili. derived significa che il movimento è stato abbinato in base al contenuto, quindi una correzione della banca può comparire come una removed e una added.
  • status è booked o pending. Una transazione in sospeso ha un proprio id. Quando la banca la contabilizza, la transazione contabilizzata arriva come added, quella in sospeso come removed con reason: pending_booked, e pending_id è valorizzato solo dove la banca li collega.
  • amount è con segno: il negativo indica denaro in uscita. direction ripete il segno.
  • bank_reference è il riferimento immutabile della registrazione assegnato dalla banca, null dove la banca non lo fornisce. Didit non lo inventa mai.
  • category è la categorizzazione propria di Didit, quando applicabile.
  • Una correzione della banca a una transazione contabilizzata è modified. Uno storno è una nuova transazione, con reverses_id quando la banca lo collega.

I campi che una banca non invia sono null

Ogni campo che una banca non invia è null. L’istituto elenca in transaction_fields i campi che si sa che invia, insieme a pending_transactions, pending_linkage, balance_types e history_days_max, così nessuno scopre lacune in produzione. Usa il cliente di test sparse_fields nel sandbox per verificare il tuo codice con una banca che invia pochi dati.

Paginazione di un intervallo di date

Continua a leggere con page_token finché has_more è vero. Il token blocca lo snapshot della lettura per un’ora: le aggiunte successive alla prima pagina non vi sono incluse, ogni riga viene restituita nel suo stato attuale, e una riga rimossa durante la paginazione non compare nelle pagine successive e appare nel change feed. Un token scaduto restituisce 410 page_expired: riavvia la lettura dalla query originale.

Il feed delle modifiche

GET /v3/bank/connections/{id}/transactions/sync/ restituisce tutte le modifiche avvenute su tutti i conti di una connessione a partire da un cursor.
  • Un cursore vuoto restituisce ogni transazione attuale come added con reset: true. Sostituisci la tua copia con questi dati invece di aggiungerli.
  • Continua a paginare con page_token finché has_more è true. Salva next_cursor solo dopo una risposta con has_more: false. Se la paginazione fallisce a metà, riparti dal cursore che avevi salvato.
  • Il cursore è opaco e vincolato alla connessione e all’ambiente. Il registro delle modifiche è riproducibile per 90 giorni. Un cursore più vecchio restituisce la risposta 410 cursor_expired con bootstrap: true: ricomincia da un cursore vuoto e sostituisci la tua copia.
  • removed[].reason può assumere i valori pending_booked, pending_expired, bank_removed o access_removed.
La versione passo per passo è in Feed bancario continuo per la contabilità.

Intestazioni

Entrambe le letture delle transazioni restituiscono le intestazioni X-RateLimit-* (600 letture e 300 scritture al minuto per applicazione, con 429 e Retry-After oltre tale soglia) e X-Bank-Last-Synced-At. I limiti delle API e i limiti della banca sul recupero dei dati sono cose separate: vedi Aggiornare i dati bancari su richiesta.
Ultima modifica il 22 novembre 2026