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_qualityindica quanto è forte questa garanzia.bank_referenceeroute_idsono stabili.derivedsignifica che il movimento è stato abbinato in base al contenuto, quindi una correzione della banca può comparire come unaremovede unaadded.statusèbookedopending. Una transazione in sospeso ha un proprio id. Quando la banca la contabilizza, la transazione contabilizzata arriva comeadded, quella in sospeso comeremovedconreason: pending_booked, epending_idè valorizzato solo dove la banca li collega.amountè con segno: il negativo indica denaro in uscita.directionripete il segno.bank_referenceè il riferimento immutabile della registrazione assegnato dalla banca,nulldove 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, conreverses_idquando 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 conpage_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
addedconreset: true. Sostituisci la tua copia con questi dati invece di aggiungerli. - Continua a paginare con
page_tokenfinchéhas_moreè true. Salvanext_cursorsolo dopo una risposta conhas_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_expiredconbootstrap: true: ricomincia da un cursore vuoto e sostituisci la tua copia. removed[].reasonpuò assumere i valoripending_booked,pending_expired,bank_removedoaccess_removed.
Intestazioni
Entrambe le letture delle transazioni restituiscono le intestazioniX-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.