# Kasse zählen (https://developer.bimetrics.de/reference/cash-book/record-cash-count)

`POST https://app.bimetrics.de/api/cash-books/{id}/counts`

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

Speichert eine Zählung der Kasse (Kassensturz) mit heutigem Datum: das gezählte Geld je Schein und Münze (`denominations`) oder nur die Summe (`totalMinor`), den Bestand laut Kassenbuch und die Differenz. Stimmt beides überein, bucht die Zählung nichts. Bei einer Differenz sind `resolution` und `reason` Pflicht: `later`, wenn eine fehlende Buchung sie erklärt, etwa ein Beleg, der noch kommt; die Zählung bucht dann nichts und die Buchung folgt wie jede andere. `booked` bucht die Differenz als Kassenfehlbetrag oder Kassenüberschuss mit eigener Nummer am heutigen Tag, ohne Umsatzsteuer, gegen Sonstige betriebliche Aufwendungen bzw. Erträge (SKR03 4900 bzw. 8603, SKR04 6300 bzw. 4830). Ein Überschuss aus einer bar bezahlten Rechnung, die noch nicht erfasst ist, ist eine Einnahme mit Umsatzsteuer und kein Überschuss: Dann gilt `later`, und die Zahlung wird am Beleg gebucht. Zählungen werden nie geändert oder gelöscht. `expectedBalanceMinor` schützt vor einer Änderung dazwischen. Zählen 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 des Kassenbuchs (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 count; expectedBalanceMinor from the last read

Schema `CashCountRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `denominations` | object | Stück je Schein und Münze, nie zusammen mit `totalMinor`. Der Schlüssel ist der Wert in Cent: `50000`, `20000`, `10000`, `5000`, `2000`, `1000`, `500` für Scheine, `200`, `100`, `50`, `20`, `10`, `5`, `2`, `1` für Münzen; je höchstens 100000 Stück. Fehlt es, gilt `totalMinor`. |
| `expectedBalanceMinor` | integer | Der zuletzt gelesene Bestand in Cent, etwa `count.expectedMinor` der Vorschau; bei `booked` Pflicht. Weicht der Bestand ab, antwortet die Route mit `409 CashBookRejected` und speichert nichts. |
| `reason` | string | Bei einer Differenz Pflicht: woher sie kommt, höchstens 120 Zeichen; steht im Buchungstext. |
| `resolution` | string: `booked`, `later` | Bei einer Differenz Pflicht: `booked` bucht sie als Kassenfehlbetrag oder Kassenüberschuss, `later` lässt sie offen, weil eine fehlende Buchung sie erklärt. |
| `totalMinor` | integer | Ohne `denominations` Pflicht: das gezählte Geld in Cent, höchstens 100000000. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/cash-books/{id}/counts" \
  -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`: CashCountResult |
| 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 (`CashCountResult`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `balanceMinor` | integer | Bestand laut Kassenbuch danach, in Cent. Bei `later` bleibt er, bis die fehlende Buchung erfasst ist. |
| `bookings` | Array<CashBookEntryBooking>, kann null sein | Die Buchungszeile der Differenz; leer ohne Buchung. |
| `count` | CashCount | Die Zählung. |
| `entry` | CashBookEntry | Bei `booked` der Eintrag der Differenzbuchung; in der Vorschau mit Nummer `neu`. |

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