# Kontenrollen einer Kassendatei ändern (https://developer.bimetrics.de/reference/cash-book/change-register-file-accounts)

`PATCH https://app.bimetrics.de/api/cash-import-files/{id}/accounts`

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

Ändert die bestätigten Rollen der Konten einer gelesenen Kassendatei (`status: read`) an ihrer Kasse. Die Kasse ist der führende Stand für alle ihre Dateien: Ein Konto in `accounts` bekommt seine neue Rolle, eine leere Rolle entfernt sie, und ein Konto, das fehlt, behält die Rolle der Kasse. Jede Änderung steht mit Person bzw. API-Schlüssel, Zeit, Kanal, Konto, alter und neuer Rolle im Protokoll. Jede Kassendatei der Kasse übernimmt die Rollen, und jeder Entwurf eines Tagesabschlusses aus den Kassendateien der Kasse, der noch nicht übernommen ist, wird mit den neuen Rollen neu gelesen, außer in einem abgeschlossenen Monat. Übernommene Tage bleiben, wie sie gebucht sind: Zum Korrigieren stornierst du den Tag (`reverseCashImport`) und lädst die Datei noch einmal hoch, dann kommt er als Entwurf mit den neuen Rollen zurück. Erlös passt nur zu einem Konto für Umsatzerlöse oder Erlösschmälerungen oder einem Erlöskonto mit Steuerautomatik, eine Anzahlung nur zu einem Konto mit Steuerautomatik, und ein Umsatzsteuerkonto bekommt keine Rolle; sonst `400 CashBookRejected` mit dem Konto im Satz. Wartet die Datei noch auf ihre Zuordnung, bestätigst du sie zuerst mit `confirmRegisterFileAccounts` (`409`); auch eine verworfene Datei gibt `409`. Gebucht wird nichts. Nur Inhaber (`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 |
| --- | --- | --- | --- | --- |
| `id` | path | ja | string (uuid) | ID der Kassendatei (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 role of each account to change; an account left out keeps its role

Schema `RegisterFileAccountsRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `accounts` | Array<RegisterFileAccount>, kann null sein | Die Konten, deren Rolle sich gegenüber der angezeigten ändert oder die der Inhaber so bestätigt; jedes höchstens einmal. Ein Konto, das fehlt, behält die angezeigte Rolle. |

### Beispiel

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

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `accounts` | Array<RegisterFileAccountRole>, kann null sein | Die Gegenkonten der Datei mit Bezeichnung und Rolle. |
| `balanceBeforeMinor` | integer | Bestand vor dem ersten Tag in Cent. |
| `batchHash` | string | Prüfsumme der gemeinsam übernehmbaren Tage. Fehlt, wenn kein Tag bereit ist. |
| `cashAccount` | integer | Kassenkonto der Datei; 0 bei DSFinV-K. |
| `cashBookId` | string (uuid) | Kassenbuch der Art `register`. |
| `chart` | string: `SKR03`, `SKR04` | Kontenrahmen der Datei: `SKR03` oder `SKR04`; fehlt bei DSFinV-K. |
| `confirmedAt` | string (date-time) | Zeitpunkt, zu dem der Inhaber die Rollen der Konten bestätigt hat. |
| `confirmedBy` | string | Name des Inhabers, der die Rollen bestätigt hat. |
| `createdAt` | string (date-time) | Zeitpunkt des Hochladens. |
| `days` | Array<RegisterFileDay>, kann null sein | Die Kassentage der Datei; ein Tag ohne Buchungen steht nicht darin. |
| `fileKey` | string | Kennung der Kasse aus Kassensystem und Kostenstelle (KOST1), etwa „belbo · KOST1 30“; bei DSFinV-K die Seriennummer der Kasse. Berater- und Mandantennummer gehören der Steuerkanzlei und zählen nicht. |
| `fileName` | string | Name der Datei beim Hochladen. |
| `format` | string: `datev`, `dsfinvk` | `datev`: DATEV-Buchungsstapel; `dsfinvk`: DSFinV-K-Export. |
| `id` | string (uuid) | ID der Kassendatei. |
| `known` | integer | Zahl der Tage, die mit denselben Zeilen schon übernommen sind und deshalb keinen Entwurf bekommen. |
| `origin` | string | Weg des Hochladens: `web`, `api` oder `mcp`. |
| `periodFrom` | NaiveDate | Beginn des Zeitraums laut Kopf der Datei. |
| `periodTo` | NaiveDate | Ende des Zeitraums laut Kopf der Datei. |
| `sameFile` | RegisterFileSame | Dieselbe Datei wurde schon einmal hochgeladen und nicht verworfen. |
| `sha256` | string | SHA-256 der Datei; sie wird nie ersetzt. |
| `sizeBytes` | integer | Größe der Datei in Byte. |
| `status` | string: `mapping`, `read`, `discarded` | `mapping` (die Konten warten auf ihre Rollen, beim ersten DSFinV-K-Export die Kasse auf ihre Bestätigung), `read` (jeder Kassentag ist ein Tagesabschluss) oder `discarded` (verworfen). |
| `uploadedBy` | string | Name der Person, die die Datei hochgeladen hat. |
| `vendor` | string | Kassensystem laut Kopf der Datei, etwa `belbo`. |

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