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

# Bankkonten, Guthaben und Transaktionen: Datenmodell

> Didit Bank-Datenmodell: Konten mit stabilen IDs, typisierte Guthaben, gebuchte/ausstehende Transaktionen und Änderungsfeed mit Cursor.

Die Bank-Daten-API von Didit speichert die Konten, Salden und Transaktionen jeder Verbindung und stellt sie über Leseendpunkte mit Paginierung bereit (`cursor` bei Listen, `page_token` bei den Transaktionsabfragen).
Beträge sind Dezimalzeichenketten mit einem separaten `currency`-Feld nach ISO 4217, Datumsangaben folgen ISO 8601, und Länder werden nach ISO alpha-3 angegeben.
Lesezugriffe werden nie abgerechnet.

## Konten

`GET /v3/bank/connections/{id}/accounts/` listet die Konten einer Verbindung auf, und `GET /v3/bank/accounts/{account_id}/` gibt ein einzelnes Konto zurück.

| Feld | Bedeutung |
| - | - |
| `id` | Gehört zur Verbindung und ändert sich, solange diese besteht, nicht, auch nicht bei Erneuerungen. |
| `account_ref` | Identifiziert dasselbe Bankkonto über alle Verbindungen einer Anwendung und Umgebung hinweg. Es ist ein schlüsselbasierter Hash der eigenen Kennungen der Bank und ist `null`, wenn die Bank keine verlässliche Kennung liefert. |
| `type`, `usage` | `current`, `savings`, `card`, `loan`, `investment` oder `other` sowie `personal`, `business` oder `unknown`. |
| `identifiers` | Die IBAN, BIC und weitere Kennungen. Aufrufer auf Serverseite mit der Berechtigung für Bankdaten erhalten sie vollständig. |
| `holders[]` | Jeder Inhaber mit einem `name` und einer `role`: `holder`, `joint_holder`, `representative` oder `unknown`. |
| `sync.last_synced_at` | Zeitpunkt, zu dem Didit die Daten zuletzt von der Bank abgerufen hat, nicht der Zeitpunkt, zu dem Sie sie zuletzt gelesen haben. |
| `history_coverage` | Was die Bank vom angefragten Verlauf geliefert hat: `requested_from`, `oldest_booking_date`, `covered_ranges`, `missing_ranges` und ein `status` mit `complete`, `partial`, `empty`, `unavailable` oder `unknown`. |

Verwenden Sie `account_ref`, um ein Bankkonto zu erkennen, wenn eine Person es erneut verbindet, und `id` für alles innerhalb einer Verbindung.

## Guthaben

`GET /v3/bank/accounts/{account_id}/balances/` liefert typisierte Guthaben mit den jeweiligen Stichtagen.

```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` ist `booked`, `available` oder `expected`, und `iso_type` enthält den ISO-20022-Code der Bank, sofern die Bank einen angibt.

## Transaktionen

`GET /v3/bank/accounts/{account_id}/transactions/` liest einen Datumsbereich.
Der Endpoint akzeptiert `date_from` und `date_to` (Kalenderdaten, wie die Bank sie meldet, jeweils einschließlich), `status` (`booked` oder `pending`, standardmäßig beide), `limit` (bis zu 500) und `page_token`.
Die Sortierung erfolgt absteigend nach `effective_date` und danach nach `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`** wird von Didit vergeben und beim ersten Auftreten gespeichert. Dieselbe Buchung behält ihre ID über alle Abfragen, Synchronisierungen und Erneuerungen hinweg.
* **`identity_quality`** gibt an, wie stark diese Garantie ist. `bank_reference` und `route_id` sind stabil. `derived` bedeutet, dass die Buchung anhand ihres Inhalts zugeordnet wurde. Eine Korrektur durch die Bank kann deshalb als ein `removed` und ein `added` erscheinen.
* **`status`** ist `booked` oder `pending`. Eine ausstehende Transaktion hat eine eigene ID. Bucht die Bank sie, erscheint die gebuchte Transaktion als `added`, die ausstehende als `removed` mit `reason: pending_booked`. `pending_id` ist nur gesetzt, wenn die Bank beide Transaktionen verknüpft.
* **`amount`** ist vorzeichenbehaftet: Ein negativer Betrag bedeutet Geldabfluss. `direction` wiederholt das Vorzeichen.
* **`bank_reference`** ist die unveränderliche Buchungsreferenz der Bank. Sie ist `null`, wenn die Bank keine liefert. Didit erzeugt diesen Wert nie selbst.
* **`category`** ist die eigene Kategorisierung von Didit, sofern eine zutrifft.
* Eine Korrektur einer gebuchten Transaktion durch die Bank wird als `modified` ausgegeben. Eine Rückbuchung ist eine neue Transaktion, mit `reverses_id`, sofern die Bank sie verknüpft.

### Felder, die eine Bank nicht übermittelt, sind null

Jedes Feld, das eine Bank nicht übermittelt, ist `null`.
Das Institut führt in `transaction_fields` die Felder auf, von denen bekannt ist, dass es sie übermittelt, zusammen mit `pending_transactions`, `pending_linkage`, `balance_types` und `history_days_max`. So fallen Lücken nicht erst in der Produktion auf.
Testen Sie Ihren Code mit dem Testkunden `sparse_fields` in der [Sandbox](https://docs.didit.me/de/core-technology/bank-verification/sandbox.md) gegen eine Bank, die nur wenige Felder sendet.

### Seitenweises Abrufen eines Datumsbereichs

Lesen Sie mit `page_token` weiter, solange `has_more` wahr ist.
Der Token fixiert den Snapshot der Abfrage für eine Stunde: Hinzufügungen nach der ersten Seite sind darin nicht enthalten, jede Zeile wird in ihrem aktuellen Zustand ausgeliefert, und eine Zeile, die während des Abrufs entfernt wird, fällt aus den späteren Seiten heraus und erscheint im Änderungsfeed.
Ein abgelaufener Token wird mit `410 page_expired` beantwortet. Starten Sie den Abruf in diesem Fall mit der ursprünglichen Abfrage neu.

## Der Änderungsfeed

`GET /v3/bank/connections/{id}/transactions/sync/` gibt alle Änderungen über alle Konten einer Verbindung seit einem `cursor` zurück.

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

* Ein leerer Cursor gibt alle aktuellen Transaktionen als `added` mit `reset: true` zurück. Ersetzen Sie Ihre Kopie damit, anstatt sie zu ergänzen.
* Blättern Sie weiter mit `page_token`, solange `has_more` true ist. Speichern Sie `next_cursor` erst nach einer Antwort mit `has_more: false`. Wenn das Blättern mittendrin fehlschlägt, starten Sie vom gespeicherten Cursor neu.
* Ein Cursor ist undurchsichtig und an die Verbindung und die Umgebung gebunden. Das Änderungsprotokoll kann 90 Tage lang erneut abgespielt werden. Ein älterer Cursor antwortet mit `410 cursor_expired` und `bootstrap: true`: Beginnen Sie erneut mit einem leeren Cursor und ersetzen Sie Ihre Kopie.
* `removed[].reason` ist `pending_booked`, `pending_expired`, `bank_removed` oder `access_removed`.

Die Schritt-für-Schritt-Anleitung finden Sie unter [Kontinuierlicher Bankfeed für die Buchhaltung](https://docs.didit.me/de/use-cases/bank-data-for-accounting.md).

## Header

Beide Transaktionsabfragen geben die Header `X-RateLimit-*` zurück (600 Lesezugriffe und 300 Schreibzugriffe pro Minute und Anwendung, darüber hinaus 429 mit `Retry-After`) sowie `X-Bank-Last-Synced-At`.
API-Rate-Limits und die eigenen Abruflimits der Bank sind getrennte Dinge: siehe [Bankdaten bei Bedarf aktualisieren](https://docs.didit.me/de/use-cases/refresh-bank-data-on-demand.md).


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