# Vorschau eines Kontoauszugs (https://developer.bimetrics.de/reference/bank-statements/preview-statement)

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

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

Liest die ganze Datei und vergleicht sie mit den Umsätzen des Kontos, ohne etwas zu buchen: neu, schon da, zu prüfen (`review`) oder vorgemerkt, nicht gelesene Zeilen, Salden, DATEV-Hinweise und Warnungen. bimetrics merkt sich diese Vorschau 60 Minuten für `applyStatement`, mit genau diesem Konto und dieser Zuordnung. Liest gerade eine andere Vorschau: `409 BankStatementBusy`, in einer Minute erneut.

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

> **Achtung:** Dieser Aufruf ist nicht als rein lesend gekennzeichnet und kann echte Daten in der Firma anlegen oder ändern. Es gibt keine Testumgebung.
>
> KI-Agenten fragen vor diesem Aufruf beim Nutzer nach.

### Authentifizierung

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

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

Upload, Konto und Zuordnung der Spalten

Schema `StatementPreviewRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `account` | StatementAccountChoice | Das Konto. |
| `mapping` | StatementMapping | Die Zuordnung. |
| `uploadId` | string (uuid) | ID des Uploads. |

### Beispiel

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

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: StatementPreview |
| 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 | Gerade liest eine andere Vorschau oder der Bankabruf (`BankStatementBusy`). In einer Minute erneut senden. | `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 (`StatementPreview`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `balance` | StatementBalance | Saldenprüfung. |
| `canApply` | boolean | Es gibt etwas zu übernehmen, und mindestens die Hälfte der Datei ist lesbar. |
| `counts` | StatementPreviewCounts | Zeilen je Stand. |
| `datev` | StatementDatevHint | Hinweis zum DATEV-Export, sonst `null`. |
| `file` | StatementPreviewFile | Die Datei. |
| `guards` | StatementGuards | Warnungen; sie sperren nichts. |
| `readableShare` | number | Anteil lesbarer Zeilen, 0 bis 1. |
| `rows` | Array<StatementPreviewRow>, kann null sein | Alle Zeilen. |
| `sameFile` | StatementSameFile | Ein Import, der diese Datei schon übernommen hat, sonst `null`. |
| `unread` | integer | Nicht gelesene Zeilen. |
| `unreadSample` | Array<StatementUnreadLine>, kann null sein | Die ersten 50 nicht gelesenen Zeilen mit Grund. |

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