# Beleg einer Auszahlung zuordnen (https://developer.bimetrics.de/reference/cash-book/settle-cash-book-entry)

`POST https://app.bimetrics.de/api/cash-book-entries/{id}/document`

operationId: `settleCashBookEntry` · Berechtigung (Scope): `matching:write` · Bereich: Kassenbuch

Ordnet einer Auszahlung aus einem Tagesabschluss (`receiptMissing`) ihren Beleg zu, wie „Zuordnen“ und „Eigenbeleg erstellen“ in der App. Mit `documentId` bucht bimetrics die Barzahlung eines offenen Eingangsbelegs, Kreditor an Kasse, wie `POST /api/match/payment`; `expectedVersion` und `expectedAmountOpenMinor` sind die zuletzt gelesenen Werte. Der offene Betrag muss die Auszahlung decken. Ohne Beleg bucht ein Eigenbeleg (`category` und `ownReceipt`) die Ausgabe ohne Vorsteuer, wie eine Ausgabe ohne Beleg. Beides zusammen oder keins ergibt `400 CashBookRejected`. Betrag und Tag kommen aus der Auszahlung: Gebucht wird am Kassentag, ein neuer Eintrag entsteht nicht. Eine Auszahlung hat höchstens einen Beleg. Nur im offenen Monat, auch in einem stillgelegten Kassenbuch. Lohn und ausgezahltes Trinkgeld brauchen keinen Beleg. Zuordnen dürfen Inhaber und Nutzer, nicht die Steuerberatung (`403 CashBookOwnerOnly`). Bei einer Wiederholung schickst du denselben Idempotency-Key.

Benötigt einen Schlüssel mit der Berechtigung `matching:write`.

> **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 |
| --- | --- | --- | --- | --- |
| `id` | path | ja | string (uuid) | ID der Auszahlung (UUID). |
| `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`)

the receipt or the own receipt

Schema `CashBookSettleRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `category` | string | Ohne Beleg Pflicht: eine Kategorie für Eingangsbelege, wie bei einer Ausgabe ohne Beleg; gesperrt sind Kategorien, für die es immer einen Beleg oder Bescheid gibt. |
| `documentId` | string (uuid) | Ein offener Eingangsbeleg, dessen offener Betrag die Auszahlung deckt. |
| `expectedAmountOpenMinor` | integer | Mit `documentId`: zuletzt gelesener offener Betrag in Cent. |
| `expectedVersion` | string | Mit `documentId`: zuletzt gelesene Version des Belegs. |
| `ownReceipt` | CashBookOwnReceipt | Ohne Beleg Pflicht: Empfänger, Zweck und Grund, je höchstens 100 Zeichen ohne doppelte Anführungszeichen. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/cash-book-entries/{id}/document" \
  -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`: CashBookSettleResult |
| 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 diesen Endpunkt (`APIKeyPermissionDenied`, `context.scope` nennt sie; Berechtigungen sind fest: neuen Schlüssel anlegen, austauschen, alten widerrufen), der Endpunkt ist für API-Schlüssel nicht freigegeben (`APIKeyPermissionDenied` ohne `context.scope`), 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 (`CashBookSettleResult`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `bookings` | Array<CashBookEntryBooking>, kann null sein | Die Buchungen des Belegs am Kassentag; leer nach der Rücknahme. |
| `entry` | CashBookEntry | Die Auszahlung mit `settlement`, nach der Rücknahme mit `receiptMissing`. |
| `replayed` | boolean | `true` bei einer Wiederholung. |

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