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

# Comptes bancaris, saldos i transaccions: model de dades

> Model de dades de comptes bancaris de Didit: saldos tipats, transaccions reservades i pendents, i un feed de canvis amb cursor.

L'API de dades bancàries de Didit emmagatzema els comptes, els saldos i les transaccions de cada connexió i els serveix mitjançant endpoints de lectura amb paginació (`cursor` a les llistes, `page_token` a les lectures de transaccions).
Els imports són cadenes decimals amb un `currency` ISO 4217 separat, les dates són ISO 8601 i els països són ISO alpha-3.
Les lectures mai no es facturen.

## Comptes

`GET /v3/bank/connections/{id}/accounts/` llista els comptes d'una connexió, i `GET /v3/bank/accounts/{account_id}/` en retorna un.

| Camp | Significat |
| - | - |
| `id` | Pertany a la connexió i no canvia mentre aquesta existeix, incloses les renovacions. |
| `account_ref` | Identifica el mateix compte bancari entre connexions d'una mateixa aplicació i entorn. És un resum (hash) amb clau dels identificadors propis del banc, i `null` quan el banc no facilita cap identificador fiable. |
| `type`, `usage` | `current`, `savings`, `card`, `loan`, `investment` o `other`, i `personal`, `business` o `unknown`. |
| `identifiers` | L'IBAN, el BIC i altres identificadors. Qui fa crides des del servidor amb el permís de dades bancàries els rep sencers. |
| `holders[]` | Cada titular amb un `name` i un `role`: `holder`, `joint_holder`, `representative` o `unknown`. |
| `sync.last_synced_at` | Quan Didit va obtenir les dades del banc per última vegada, no quan tu les vas llegir per última vegada. |
| `history_coverage` | Què ha lliurat el banc de l'historial que has sol·licitat: `requested_from`, `oldest_booking_date`, `covered_ranges`, `missing_ranges` i un `status` amb els valors `complete`, `partial`, `empty`, `unavailable` o `unknown`. |

Fes servir `account_ref` per reconèixer un compte bancari quan una persona el torna a connectar, i `id` per a tot el que hi ha dins d'una mateixa connexió.

## Saldos

`GET /v3/bank/accounts/{account_id}/balances/` retorna els saldos tipificats amb les seves dates de referència.

```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` és `booked`, `available` o `expected`, i `iso_type` conté el codi ISO 20022 del banc quan el banc el proporciona.

## Transaccions

`GET /v3/bank/accounts/{account_id}/transactions/` llegeix un interval de dates.
Accepta `date_from` i `date_to` (dates de calendari tal com les informa el banc, incloses), `status` (`booked` o `pending`, els dos per defecte), `limit` (fins a 500) i `page_token`.
Ordena per `effective_date` de manera descendent i, després, 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`** és de Didit i s'emmagatzema la primera vegada que es veu. El mateix moviment conserva el seu id entre lectures, sincronitzacions i renovacions.
* **`identity_quality`** indica com de sòlida és aquesta garantia. `bank_reference` i `route_id` són estables. `derived` vol dir que el moviment s'ha identificat pel seu contingut, de manera que una correcció del banc pot aparèixer com un `removed` i un `added`.
* **`status`** és `booked` o `pending`. Una transacció pendent té el seu propi id. Quan el banc la comptabilitza, la transacció comptabilitzada arriba com a `added`, i la pendent com a `removed` amb `reason: pending_booked`. `pending_id` només s'informa quan el banc les enllaça.
* **`amount`** és amb signe: un valor negatiu vol dir diners que surten. `direction` repeteix el signe.
* **`bank_reference`** és la referència d'entrada immutable del banc, i és `null` quan el banc no la facilita. Didit mai no la inventa.
* **`category`** és la categorització pròpia de Didit, quan és aplicable.
* Una correcció del banc sobre una transacció comptabilitzada és `modified`. Una anul·lació és una transacció nova, amb `reverses_id` quan el banc la enllaça.

### Els camps que un banc no envia són null

Tots els camps que un banc no envia són `null`.
L'entitat enumera a `transaction_fields` els camps que se sap que envia, juntament amb `pending_transactions`, `pending_linkage`, `balance_types` i `history_days_max`, perquè ningú descobreixi buits en producció.
Utilitza el client de prova `sparse_fields` del [sandbox](https://docs.didit.me/ca/core-technology/bank-verification/sandbox.md) per provar el teu codi amb un banc que envia poca informació.

### Paginació d'un interval de dates

Continua llegint amb `page_token` mentre `has_more` sigui true.
El token fixa la instantània de la lectura durant una hora: les addicions posteriors a la primera pàgina no hi són, cada fila es serveix en el seu estat actual, i una fila eliminada durant la paginació deixa de sortir a les pàgines següents i apareix al flux de canvis.
Un token caducat respon amb `410 page_expired`: reinicia la lectura des de la seva consulta original.

## El flux de canvis

`GET /v3/bank/connections/{id}/transactions/sync/` retorna els canvis de tots els comptes d'una connexió des d'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 cursor buit retorna totes les transaccions actuals com a `added` amb `reset: true`. Substitueix la teva còpia per aquestes dades en lloc d'afegir-les-hi.
* Continua paginant amb `page_token` mentre `has_more` sigui true. Emmagatzema `next_cursor` només després d'una resposta amb `has_more: false`. Si la paginació falla a mig camí, reinicia des del cursor que havies emmagatzemat.
* Un cursor és opac i està vinculat a la connexió i a l'entorn. El registre de canvis es pot reproduir durant 90 dies. Un cursor més antic respon amb `410 cursor_expired` i `bootstrap: true`: torna a començar des d'un cursor buit i substitueix la teva còpia.
* `removed[].reason` és `pending_booked`, `pending_expired`, `bank_removed` o `access_removed`.

La versió pas a pas és a [Flux bancari continu per a la comptabilitat](https://docs.didit.me/ca/use-cases/bank-data-for-accounting.md).

## Capçaleres

Totes dues consultes de transaccions retornen les capçaleres `X-RateLimit-*` (600 lectures i 300 escriptures per minut per aplicació, i un 429 amb `Retry-After` quan se superen aquests límits) i `X-Bank-Last-Synced-At`.
Els límits de l'API i els límits propis del banc per a les consultes són coses diferents: consulta [Actualitzar les dades bancàries sota demanda](https://docs.didit.me/ca/use-cases/refresh-bank-data-on-demand.md).


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