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

# Cuentas bancarias, saldos y transacciones: modelo de datos

> Modelo de datos bancario de Didit: cuentas con ids estables, saldos tipados, transacciones contabilizadas y pendientes, y feed de cambios con cursor.

La API de datos bancarios de Didit almacena las cuentas, los saldos y las transacciones de cada conexión, y los entrega mediante endpoints de lectura con paginación (`cursor` en las listas, `page_token` en las lecturas de transacciones).
Los importes son cadenas decimales con un campo `currency` ISO 4217 independiente, las fechas siguen ISO 8601 y los países usan ISO alpha-3.
Las lecturas nunca se facturan.

## Cuentas

`GET /v3/bank/connections/{id}/accounts/` lista las cuentas de una conexión, y `GET /v3/bank/accounts/{account_id}/` devuelve una.

| Campo | Significado |
| - | - |
| `id` | Pertenece a la conexión y no cambia mientras esta exista, incluidas las renovaciones. |
| `account_ref` | Identifica la misma cuenta bancaria en distintas conexiones de una misma aplicación y entorno. Es un hash con clave de los identificadores propios del banco, y es `null` cuando el banco no proporciona un identificador fiable. |
| `type`, `usage` | `current`, `savings`, `card`, `loan`, `investment` u `other`, y `personal`, `business` o `unknown`. |
| `identifiers` | El IBAN, el BIC y otros identificadores. Los clientes que invocan la API desde el servidor y tienen el permiso de datos bancarios los reciben completos. |
| `holders[]` | Cada titular con un `name` y un `role`: `holder`, `joint_holder`, `representative` o `unknown`. |
| `sync.last_synced_at` | Cuándo Didit obtuvo los datos del banco, no cuándo los leíste tú por última vez. |
| `history_coverage` | Lo que entregó el banco del historial que solicitaste: `requested_from`, `oldest_booking_date`, `covered_ranges`, `missing_ranges` y un `status` con valores `complete`, `partial`, `empty`, `unavailable` o `unknown`. |

Usa `account_ref` para reconocer una cuenta bancaria cuando una persona la conecta de nuevo, e `id` para todo lo que esté dentro de una misma conexión.

## Saldos

`GET /v3/bank/accounts/{account_id}/balances/` devuelve los saldos clasificados por tipo, con sus fechas de referencia.

```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` toma uno de los valores `booked`, `available` o `expected`, y `iso_type` contiene el código ISO 20022 del banco cuando este lo proporciona.

## Transacciones

`GET /v3/bank/accounts/{account_id}/transactions/` lee un rango de fechas.
Acepta `date_from` y `date_to` (fechas de calendario tal como las informa el banco, ambas incluidas), `status` (`booked` o `pending`, ambos por defecto), `limit` (hasta 500) y `page_token`.
Ordena por `effective_date` descendente y, después, por `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`** es de Didit y se almacena en el primer momento en que aparece. El mismo movimiento conserva su id entre lecturas, sincronizaciones y renovaciones.
* **`identity_quality`** indica la solidez de esa garantía. `bank_reference` y `route_id` son estables. `derived` significa que el movimiento se emparejó por su contenido, de modo que una corrección del banco puede aparecer como un `removed` y un `added`.
* **`status`** es `booked` o `pending`. Una transacción pendiente tiene su propio id. Cuando el banco la contabiliza, la transacción contabilizada llega como `added` y la pendiente como `removed` con `reason: pending_booked`; `pending_id` solo se informa cuando el banco vincula ambas.
* **`amount`** lleva signo: un valor negativo es dinero que sale. `direction` repite el signo.
* **`bank_reference`** es la referencia inmutable del asiento que asigna el banco, y es `null` cuando el banco no la proporciona. Didit nunca la inventa.
* **`category`** es la categorización propia de Didit, cuando corresponde.
* Una corrección del banco sobre una transacción contabilizada aparece como `modified`. Una anulación es una transacción nueva, con `reverses_id` cuando el banco la vincula.

### Los campos que un banco no envía son null

Todo campo que un banco no envía se devuelve como `null`.
La entidad enumera los campos que sabe que envía en `transaction_fields`, junto con `pending_transactions`, `pending_linkage`, `balance_types` e `history_days_max`, para que nadie descubra huecos en producción.
Usa el cliente de prueba `sparse_fields` del [sandbox](https://docs.didit.me/es/core-technology/bank-verification/sandbox.md) para probar tu código con un banco que envía pocos datos.

### Paginar un rango de fechas

Sigue leyendo con `page_token` mientras `has_more` sea true.
El token fija la instantánea de la lectura durante una hora: las adiciones posteriores a la primera página no están incluidas, cada fila se sirve en su estado actual, y una fila eliminada durante la paginación deja de aparecer en las páginas siguientes y sí aparece en el feed de cambios.
Un token expirado responde `410 page_expired`: reinicia la lectura desde su consulta original.

## El flujo de cambios

`GET /v3/bank/connections/{id}/transactions/sync/` devuelve lo que ha cambiado en todas las cuentas de una conexión desde 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 vacío devuelve todas las transacciones actuales como `added` con `reset: true`. Sustituye tu copia por esos datos en lugar de añadirlos a ella.
* Sigue paginando con `page_token` mientras `has_more` sea verdadero. Guarda `next_cursor` solo después de una respuesta con `has_more: false`, y si la paginación falla a mitad de camino, reinicia desde el cursor que guardaste.
* Un cursor es opaco y está vinculado a la conexión y al entorno. El registro de cambios se puede reproducir durante 90 días. Un cursor más antiguo devuelve `410 cursor_expired` con `bootstrap: true`: vuelve a empezar desde un cursor vacío y sustituye tu copia.
* `removed[].reason` es `pending_booked`, `pending_expired`, `bank_removed` o `access_removed`.

La versión paso a paso está en [Flujo bancario continuo para contabilidad](https://docs.didit.me/es/use-cases/bank-data-for-accounting.md).

## Encabezados

Ambas lecturas de transacciones devuelven los encabezados `X-RateLimit-*` (600 lecturas y 300 escrituras por minuto y por aplicación, y 429 con `Retry-After` cuando se superan esos límites) y `X-Bank-Last-Synced-At`.
Los límites de la API y los límites propios del banco para la obtención de datos son cosas distintas: consulta [Actualizar datos bancarios bajo demanda](https://docs.didit.me/es/use-cases/refresh-bank-data-on-demand.md).


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