> ## 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.

# Conti bancari, saldi e transazioni: modello dei dati

> Il modello dati Bank di Didit: conti con ID stabili, saldi tipizzati, transazioni contabilizzate e in sospeso, e un feed delle modifiche con cursore durevole.

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.

| Campo | Significato |
| - | - |
| `id` | Appartiene alla connessione e non cambia finché questa esiste, rinnovi compresi. |
| `account_ref` | Identifica lo stesso conto bancario tra le connessioni di una stessa applicazione e di uno stesso ambiente. È un hash con chiave degli identificativi propri della banca, ed è `null` quando la banca non fornisce un identificativo affidabile. |
| `type`, `usage` | `current`, `savings`, `card`, `loan`, `investment` o `other`, e `personal`, `business` o `unknown`. |
| `identifiers` | L'IBAN, il BIC e gli altri identificativi. I chiamanti lato server con l'autorizzazione ai dati bancari li ricevono per intero. |
| `holders[]` | Ogni intestatario con un `name` e un `role`: `holder`, `joint_holder`, `representative` o `unknown`. |
| `sync.last_synced_at` | Il momento in cui Didit ha recuperato i dati dalla banca, non quando tu li hai letti l'ultima volta. |
| `history_coverage` | Ciò che la banca ha fornito dello storico richiesto: `requested_from`, `oldest_booking_date`, `covered_ranges`, `missing_ranges` e uno `status` tra `complete`, `partial`, `empty`, `unavailable` o `unknown`. |

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.

```json theme={null}
{
  "account_id": "a71f0c2e-...",
  "balances": [
    { "type": "booked", "amount": "18250.34", "currency": "EUR", "reference_date": "2026-11-20" },
    { "type": "available", "amount": "17990.34", "currency": "EUR", "reference_date": "2026-11-21" }
  ],
  "last_synced_at": "2026-11-21T12:04:40Z"
}
```

`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`.

```json theme={null}
{
  "id": "8f2b...",
  "status": "booked",
  "booking_date": "2026-11-19",
  "value_date": "2026-11-20",
  "amount": "-1210.00",
  "currency": "EUR",
  "direction": "debit",
  "description": "RECIBO SEGURIDAD SOCIAL",
  "counterparty": { "name": "TESORERIA GENERAL SEG SOCIAL", "iban": "ES7620770024003102575766" },
  "remittance": { "unstructured": ["RECIBO SEGURIDAD SOCIAL 10/2026"], "reference": "0028123456789" },
  "bank_transaction_code": "PMNT-RDDT-ESDD",
  "bank_reference": "2026111900012345",
  "identity_quality": "bank_reference",
  "balance_after": "18250.34",
  "category": "taxes_and_social_security"
}
```

* **`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](https://docs.didit.me/it/core-technology/bank-verification/sandbox.md) 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`.

```json theme={null}
{
  "added": [ { "id": "...", "status": "booked", "amount": "-35.00" } ],
  "modified": [],
  "removed": [ { "id": "...", "reason": "pending_booked" } ],
  "has_more": false,
  "next_cursor": "...",
  "reset": false
}
```

* 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à](https://docs.didit.me/it/use-cases/bank-data-for-accounting.md).

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


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