# Kassenbuch ein- oder ausschalten (https://developer.bimetrics.de/reference/cash-book/set-cash-book-enabled)

`PUT https://app.bimetrics.de/api/settings/cash-book`

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

Schaltet das Kassenbuch für die Firma ein oder aus, wie der Schalter „Kassenbuch verwenden“ in den Einstellungen. Eingeschaltet sieht das ganze Team den Menüpunkt Kassenbuch. Ausschalten geht erst, wenn kein Kassenbuch mehr in Gebrauch ist, sonst `409 CashBookRejected`. Nur ein Inhaber darf schalten, sonst `403 CashBookOwnerOnly`. Bei einer Wiederholung schickst du denselben Idempotency-Key.

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`)

on or off

Schema `CashBookSwitchRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `enabled` | boolean | `true` schaltet das Kassenbuch ein, `false` aus. |

### Beispiel

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

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `accounts` | Array<integer>, kann null sein | Kassenkonten, die ein neues Kassenbuch nehmen kann, das nächste freie zuerst; leer, wenn drei Kassenbücher in Gebrauch sind. |
| `ask` | boolean | `true`, solange die App den Inhaber in „Erste Schritte“ fragt, ob die Firma eine Kasse mit Bargeld hat. Gefragt werden nur Firmen, die sich registriert haben, seit es das Kassenbuch gibt; bei älteren bleibt das Feld `false`. Die Frage entfällt, sobald ein Inhaber das Kassenbuch ein- oder ausschaltet. |
| `canBook` | boolean | `true` für Inhaber und Nutzer: Sie dürfen buchen und stornieren, im Kassenbuch und mit „Bar“ am Beleg. Die Steuerberatung liest nur. |
| `canChange` | boolean | `true` für Inhaber: Sie dürfen das Kassenbuch ein- und ausschalten und Kassenbücher anlegen, umbenennen und stilllegen. |
| `deposit` | string | Wie eine Einlage in die Kasse gebucht wird: `owner` als Privateinlage, `shareholder` über das Gesellschafter-Verrechnungskonto. Leer, wenn die Rechtsform fehlt oder keine Einlage kennt. |
| `enabled` | boolean | `true`, wenn die Firma das Kassenbuch verwendet; die App zeigt dann den Menüpunkt Kassenbuch. |
| `inUse` | integer | Zahl der Kassenbücher, die nicht stillgelegt sind. Solange es eins gibt, lässt sich das Kassenbuch nicht ausschalten. |

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