> ## 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 bancaires, soldes et transactions : modèle de données

> Modèle Bank de Didit : comptes à identifiants stables, soldes typés, transactions comptabilisées et en attente, flux de changements à curseur durable.

L'API de données bancaires de Didit stocke les comptes, soldes et transactions de chaque connexion et les restitue via des endpoints de lecture avec pagination (`cursor` pour les listes, `page_token` pour les lectures de transactions).
Les montants sont des chaînes décimales accompagnées d'un `currency` ISO 4217 séparé, les dates suivent la norme ISO 8601 et les pays sont codés en ISO alpha-3.
Les lectures ne sont jamais facturées.

## Comptes

`GET /v3/bank/connections/{id}/accounts/` liste les comptes d'une connexion, et `GET /v3/bank/accounts/{account_id}/` en renvoie un seul.

| Champ | Signification |
| - | - |
| `id` | Rattaché à la connexion, il ne change jamais tant qu'elle existe, renouvellements compris. |
| `account_ref` | Identifie un même compte bancaire entre les connexions d'une même application et d'un même environnement. Il s'agit d'une empreinte à clé des identifiants propres à la banque, et sa valeur est `null` lorsque la banque ne fournit aucun identifiant fiable. |
| `type`, `usage` | `current`, `savings`, `card`, `loan`, `investment` ou `other` pour type, et `personal`, `business` ou `unknown` pour usage. |
| `identifiers` | L'IBAN, le BIC et les autres identifiants. Les appelants côté serveur disposant de l'autorisation d'accès aux données bancaires les reçoivent en entier. |
| `holders[]` | Chaque titulaire, avec un `name` et un `role` : `holder`, `joint_holder`, `representative` ou `unknown`. |
| `sync.last_synced_at` | Le moment où Didit a récupéré pour la dernière fois les données auprès de la banque, et non le moment où vous les avez lues pour la dernière fois. |
| `history_coverage` | Ce que la banque a fourni de l'historique demandé : `requested_from`, `oldest_booking_date`, `covered_ranges`, `missing_ranges` et un `status` égal à `complete`, `partial`, `empty`, `unavailable` ou `unknown`. |

Utilisez `account_ref` pour reconnaître un compte bancaire lorsqu'une personne connecte à nouveau ce compte, et `id` pour tout ce qui concerne une même connexion.

## Soldes

`GET /v3/bank/accounts/{account_id}/balances/` renvoie les soldes typés, avec leurs dates de référence.

```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` vaut `booked`, `available` ou `expected`, et `iso_type` contient le code ISO 20022 de la banque lorsque celle-ci en fournit un.

## Transactions

`GET /v3/bank/accounts/{account_id}/transactions/` lit une plage de dates.
Il accepte `date_from` et `date_to` (dates calendaires telles que la banque les communique, bornes incluses), `status` (`booked` ou `pending`, les deux par défaut), `limit` (jusqu'à 500) et `page_token`.
Les résultats sont triés par `effective_date` décroissant, puis par `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`** est attribué par Didit au premier passage du mouvement. Le même mouvement conserve son id d'une lecture, d'une synchronisation ou d'un renouvellement à l'autre.
* **`identity_quality`** indique la solidité de cette garantie. `bank_reference` et `route_id` sont stables. `derived` signifie que le mouvement a été rapproché sur son contenu : une correction de la banque peut donc apparaître sous la forme d'un `removed` suivi d'un `added`.
* **`status`** vaut `booked` ou `pending`. Une transaction en attente a son propre id. Lorsque la banque la comptabilise, la transaction comptabilisée arrive en `added`, et la transaction en attente en `removed` avec `reason: pending_booked`. `pending_id` n'est renseigné que lorsque la banque les relie.
* **`amount`** est signé : un montant négatif correspond à une sortie d'argent. `direction` répète ce signe.
* **`bank_reference`** est la référence immuable de l'écriture donnée par la banque, `null` lorsque la banque n'en fournit pas. Didit ne l'invente jamais.
* **`category`** est la catégorisation propre à Didit, lorsqu'elle s'applique.
* Une correction de la banque sur une transaction comptabilisée est un `modified`. Une annulation constitue une nouvelle transaction, accompagnée de `reverses_id` lorsque la banque la relie.

### Les champs qu'une banque n'envoie pas valent null

Tout champ qu'une banque n'envoie pas vaut `null`.
L'institution liste les champs qu'elle transmet dans `transaction_fields`, ainsi que `pending_transactions`, `pending_linkage`, `balance_types` et `history_days_max`, afin que personne ne découvre des lacunes en production.
Utilisez le client de test `sparse_fields` dans le [sandbox](https://docs.didit.me/fr/core-technology/bank-verification/sandbox.md) pour tester votre code avec une banque qui transmet peu de données.

### Pagination d'une plage de dates

Continuez la lecture avec `page_token` tant que `has_more` vaut true.
Le jeton fige l'instantané de la lecture pendant une heure : les ajouts survenus après la première page n'y figurent pas, chaque ligne est servie dans son état actuel, et une ligne supprimée pendant la pagination disparaît des pages suivantes et apparaît dans le flux de modifications.
Un jeton expiré renvoie `410 page_expired` : relancez la lecture depuis sa requête d'origine.

## Le flux des modifications

`GET /v3/bank/connections/{id}/transactions/sync/` renvoie les modifications survenues sur l'ensemble des comptes d'une connexion depuis 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 curseur vide renvoie toutes les transactions actuelles sous la forme `added` avec `reset: true`. Remplacez votre copie par ces données au lieu de les ajouter.
* Continuez à paginer avec `page_token` tant que `has_more` vaut true. Enregistrez `next_cursor` uniquement après une réponse avec `has_more: false`. Si la pagination échoue en cours de route, repartez du curseur que vous avez enregistré.
* Un curseur est opaque et lié à la connexion et à l'environnement. Le journal des modifications est rejouable pendant 90 jours. Un curseur plus ancien reçoit la réponse `410 cursor_expired` avec `bootstrap: true` : recommencez à partir d'un curseur vide et remplacez votre copie.
* `removed[].reason` peut valoir `pending_booked`, `pending_expired`, `bank_removed` ou `access_removed`.

La version pas à pas se trouve dans [Flux bancaire continu pour la comptabilité](https://docs.didit.me/fr/use-cases/bank-data-for-accounting.md).

## En-têtes

Les deux lectures de transactions renvoient les en-têtes `X-RateLimit-*` (600 lectures et 300 écritures par minute et par application, avec une réponse 429 et l'en-tête `Retry-After` au-delà de cette limite) ainsi que `X-Bank-Last-Synced-At`.
Les limites de l'API et les limites propres à la banque pour la récupération des données sont distinctes : consultez [Actualiser les données bancaires à la demande](https://docs.didit.me/fr/use-cases/refresh-bank-data-on-demand.md).


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