# Kassenbuch anlegen (https://developer.bimetrics.de/reference/cash-book/create-cash-book)

`POST https://app.bimetrics.de/api/cash-books`

operationId: `createCashBook` · Berechtigung (Scope): `company:write` · Bereich: Kassenbuch

Legt ein Kassenbuch an, wie das Formular in den Einstellungen. Das Kassenbuch muss eingeschaltet sein. Pflicht sind `kind`, `name` und `startDate`, das heute oder früher liegt; ohne `account` nimmt bimetrics das nächste freie Kassenkonto. Liegt `openingBalanceMinor` über 0, ist `openingSource` Pflicht; daraus und aus Kontenrahmen und Rechtsform folgt das Gegenkonto (`openingContraAccount`), das danach fest bleibt. Art, Kassenkonto, Beginn und Anfangsbestand lassen sich später nicht mehr ändern. Eine Firma hat höchstens drei Kassenbücher gleichzeitig in Gebrauch. Verstößt die Anfrage gegen eine Regel, antwortet die Route mit `400` oder `409 CashBookRejected`, `context.field` nennt das Feld und `context.message` den Satz der App. Nur ein Inhaber darf anlegen.

Benötigt einen Schlüssel mit der Berechtigung `company: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 |
| --- | --- | --- | --- | --- |
| `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 cash book

Schema `CashBookCreateRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `account` | integer | Eines der Kassenkonten aus `GET /api/settings/cash-book`; ohne Angabe das nächste freie. |
| `kind` | string: `petty`, `shop`, `register` | Pflicht: `petty` für eine Handkasse. `shop` (offene Ladenkasse) und `register` (Kassensystem mit TSE) lehnt das Anlegen vorerst mit `400` und Feld `kind` ab, bis bimetrics ihre Tageseinnahmen kann. |
| `name` | string | Pflicht: Name, höchstens 60 Zeichen und eindeutig unter den Kassenbüchern in Gebrauch, etwa „Werkstattkasse“. |
| `openingBalanceMinor` | integer | Geld in der Kasse zu Beginn von `startDate`, in Cent, höchstens 100000000 (1.000.000 €). Ohne Angabe 0. |
| `openingPerson` | string | Nur bei `openingSource` `deposit`: wer das Geld eingelegt hat, höchstens 100 Zeichen. Bei GmbH, UG, GbR und OHG Pflicht. |
| `openingSource` | string: `deposit`, `bank`, `carried_forward` | Herkunft des Anfangsbestands: `deposit` (eigenes Geld des Inhabers bzw. der Gesellschafter), `bank` (vom Geschäftskonto geholt, als Geldtransit) oder `carried_forward` (steht schon in der Buchhaltung oder die Steuerberatung bucht den Betrag selbst, bimetrics bucht nichts). Fehlt bei einem Anfangsbestand von 0. Pflicht bei einem Anfangsbestand über 0. |
| `startDate` | NaiveDate | Pflicht: Erster Tag, für den das Kassenbuch den Bestand führt. Heute oder früher, etwa der Tag des ältesten Barbelegs. |

### Beispiel

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

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `account` | integer | Kassenkonto im Kontenrahmen der Firma: 1000, 1010 oder 1020 in SKR03, 1600, 1610 oder 1620 in SKR04. |
| `archivedAt` | string (date-time) | Stillgelegt seit diesem Zeitpunkt. Fehlt, solange das Kassenbuch in Gebrauch ist. |
| `balanceMinor` | integer | Geld, das jetzt in der Kasse sein muss, in Cent. |
| `companyId` | string (uuid) | ID der Firma. |
| `createdAt` | string (date-time) | Anlage in bimetrics. |
| `id` | string (uuid) | ID des Kassenbuchs. |
| `kind` | string: `petty`, `shop`, `register` | `petty` für eine Handkasse. `shop` (offene Ladenkasse) und `register` (Kassensystem mit TSE) lehnt das Anlegen vorerst mit `400` und Feld `kind` ab, bis bimetrics ihre Tageseinnahmen kann. |
| `name` | string | Name, höchstens 60 Zeichen und eindeutig unter den Kassenbüchern in Gebrauch, etwa „Werkstattkasse“. |
| `numberPrefix` | string | Anfang der Nummern seiner Einträge: `KB` beim ersten Kassenbuch der Firma, bei weiteren `KB-` und ein Buchstabe. |
| `openingBalanceMinor` | integer | Geld in der Kasse zu Beginn von `startDate`, in Cent, höchstens 100000000 (1.000.000 €). |
| `openingContraAccount` | integer | Gegenkonto des Anfangsbestands, beim Anlegen aus Kontenrahmen und Rechtsform bestimmt und danach fest: Privateinlage, Gesellschafter-Verrechnung oder Geldtransit; `0` bei `carried_forward`. Fehlt bei einem Anfangsbestand von 0. |
| `openingPerson` | string | Wer den Anfangsbestand eingelegt hat, bei Herkunft `deposit`; steht auf dem Eigenbeleg des Anfangsbestands. |
| `openingSource` | string: `deposit`, `bank`, `carried_forward` | Herkunft des Anfangsbestands: `deposit` (eigenes Geld des Inhabers bzw. der Gesellschafter), `bank` (vom Geschäftskonto geholt, als Geldtransit) oder `carried_forward` (steht schon in der Buchhaltung oder die Steuerberatung bucht den Betrag selbst, bimetrics bucht nichts). Fehlt bei einem Anfangsbestand von 0. |
| `startDate` | NaiveDate | Erster Tag, für den das Kassenbuch den Bestand führt. |
| `updatedAt` | string (date-time) | Letzte Änderung. |

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