# Kontoauszug übernehmen (https://developer.bimetrics.de/reference/bank-statements/apply-statement)

`POST https://app.bimetrics.de/api/bankstatement/apply`

operationId: `applyStatement` · Berechtigung (Scope): `statements:import` · Bereich: Kontoauszüge

Übernimmt, was die Vorschau gezeigt hat: Jede neue Zeile wird zum Umsatz mit Buchung und automatischer Zuordnung, im Hintergrund. Das lässt sich nicht rückgängig machen. Ohne Vorschau mit genau diesem Konto und dieser Zuordnung aus den letzten 60 Minuten: `409 BankStatementPreviewRequired`. Prüf-Fälle werden nur geschrieben, wenn `includeReviewPositions` sie nennt, und nur solche, die die Vorschau gezeigt hat. Unter 50 % lesbaren Zeilen oder ohne etwas zu übernehmen: `409 BankStatementNothingToApply`. Beim Einlesen vergleicht bimetrics noch einmal, die Zahlen können also abweichen; `getStatementImport` nennt das Ergebnis. Dieselbe Datei wird nur einmal übernommen (`409 BankStatementAlreadyImported`).

Benötigt einen Schlüssel mit der Berechtigung `statements:import`.

> **Achtung:** Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
>
> KI-Agenten fragen vor diesem Aufruf beim Nutzer nach.

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | ja | string | Stabiler Schlüssel für genau diese Änderung: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bei Wiederholungen denselben Schlüssel und unveränderten Inhalt senden; das Ergebnis wird nicht nochmals erzeugt. |

### Request-Body (`application/json`)

Upload, Konto, Zuordnung der Spalten und Prüf-Fälle

Schema `StatementApplyRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `account` | StatementAccountChoice | Das Konto der Vorschau. |
| `includeReviewPositions` | Array<integer>, kann null sein | `pos` der Prüf-Fälle, die trotzdem übernommen werden sollen. Nur solche, die die Vorschau gezeigt hat. |
| `mapping` | StatementMapping | Die Zuordnung der Vorschau. |
| `reviewPositions` | Array<integer> | Wird mit einem Schlüssel nicht beachtet: bimetrics nimmt die gezeigten Prüf-Fälle aus der Vorschau. |
| `uploadId` | string (uuid) | ID des Uploads. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/bankstatement/apply" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "Idempotency-Key: rechnung-2026-001" \
  -H "Content-Type: application/json" \
  -d '{"kind":"and","children":[],"limit":50,"offset":0}'
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: StatementImport |
| 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error |
| 403 | Dem Schlüssel fehlt die Berechtigung für diese Route (`APIKeyPermissionDenied`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 404 | Nicht gefunden (`NotFound`). | `application/json`: Error |
| 409 | Versionskonflikt (`VersionConflict`), abweichender Inhalt für denselben Idempotency-Key (`IdempotencyConflict`), Dublette (`ContactDuplicate`) oder fachlich gesperrte Änderung. Aktuellen Zustand laden und prüfen; keinen anderen Schlüssel verwenden, um einen Konflikt zu umgehen. | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |

#### Felder der Antwort 200 (`StatementImport`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `accountName` | string | Name des Kontos. |
| `bankAccountId` | string (uuid) | ID des Kontos. |
| `canRetry` | boolean | Der Import lässt sich wiederholen. |
| `createdAt` | string (date-time) | Zeitpunkt der Übernahme. |
| `createdBy` | string | Wer übernommen hat. |
| `errorCode` | string, kann null sein | Grund bei `failed`. |
| `fileName` | string | Name der Datei. |
| `finishedAt` | string (date-time), kann null sein | Ende des Imports. |
| `from` | string | Erster Buchungstag der Datei, leer vor dem Vergleich. |
| `id` | string (uuid) | ID des Imports. |
| `jobId` | string (uuid) | ID des Hintergrundauftrags. |
| `progress` | StatementImportProgress | Fortschritt. |
| `result` | StatementImportResult | Das Ergebnis, sobald der Import fertig ist. |
| `state` | string | `queued`, `running`, `waiting`, `done` oder `failed`. |
| `to` | string | Letzter Buchungstag der Datei. |
| `waitReason` | string, kann null sein | Worauf der Import wartet, etwa den Bankabruf. |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json