# Eigenes Sachkonto anlegen (https://developer.bimetrics.de/reference/ledger-accounts/create-ledger-account)

`POST https://app.bimetrics.de/api/ledger-accounts`

operationId: `createLedgerAccount` · Berechtigung (Scope): `company:write` · Bereich: Eigene Sachkonten

Legt ein eigenes Sachkonto mit Nummer und Bezeichnung an. Die Nummer hat genau so viele Stellen wie die Sachkontenlänge der Firma (4 bis 8, in den DATEV-Einstellungen der App). Ihre ersten vier Stellen sind ein Erlös- oder Aufwandskonto im Bereich eines Kontos, auf das eine Kategorie bucht. Über vier Stellen sind die angehängten Stellen nie alle 0, denn dann wäre es das Standardkonto selbst: Bei Länge 5 ist 44000 das Konto 4400, 44001 ein eigenes. Bei Länge 4 ist es ein freies Konto des Bereichs, auf das keine Kategorie bucht. Die Nummer steht danach fest, sie ist je Firma eindeutig, auch gegenüber archivierten. Die Bezeichnung geht mit dem nächsten DATEV-Export an DATEV. Verstößt die Anfrage gegen eine Regel, antwortet die Route mit `400 LedgerAccountRejected`, `context.field` nennt das Feld und `context.message` den Satz der App; eine vergebene Nummer ergibt `409 LedgerAccountRejected`. 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`)

number and name

Schema `LedgerAccountRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `expectedUpdatedAt` | string (date-time) | Nur beim Ändern: das zuletzt gelesene `updatedAt`, unverändert mit allen Nachkommastellen. Für API-Schlüssel Pflicht. |
| `name` | string | Bezeichnung, höchstens 40 Zeichen in einer Zeile, etwa „Erlöse Wartungsverträge“. DATEV bekommt sie in den Kontenbeschriftungen. |
| `number` | integer | Beim Anlegen Pflicht: Das Konto, wie DATEV es bekommt, mit so vielen Stellen wie die Sachkontenlänge der Firma; eine führende Null gehört nicht zur Zahl. Je Firma eindeutig. Beim Ändern ohne Wirkung. |

### Beispiel

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

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `accountClass` | integer | Erste Stelle des vierstelligen Kontos (Kontenklasse). Fehlt wie `baseAccount`. |
| `archivedAt` | string (date-time) | Archiviert seit diesem Zeitpunkt: lässt sich nicht mehr auswählen, Buchungen behalten es, DATEV bekommt die Bezeichnung weiter. Fehlt, solange aktiv. |
| `baseAccount` | integer | Vierstelliges Konto einer Kategorie im selben Bereich; in bimetrics bleiben die Buchungen darauf. Fehlt, wenn keine Kategorie mehr in diesem Bereich bucht. |
| `companyId` | string (uuid) | ID der Firma. |
| `createdAt` | string (date-time) | Anlage in bimetrics. |
| `display` | string | Die Nummer mit den führenden Nullen der Sachkontenlänge, wie DATEV sie zeigt. |
| `id` | string (uuid) | ID des eigenen Sachkontos. |
| `name` | string | Bezeichnung, höchstens 40 Zeichen in einer Zeile, etwa „Erlöse Wartungsverträge“. DATEV bekommt sie in den Kontenbeschriftungen. Vom Nutzer eingegebener Text. |
| `number` | integer | Das Konto, wie DATEV es bekommt, mit so vielen Stellen wie die Sachkontenlänge der Firma; eine führende Null gehört nicht zur Zahl. Je Firma eindeutig. |
| `rangeFrom` | integer | Erstes vierstelliges Konto des Bereichs. Eine Position, deren Kategorie auf ein Konto von `rangeFrom` bis `rangeTo` bucht, kann das eigene Konto tragen. Fehlt wie `baseAccount`. |
| `rangeLabel` | string | Name des Bereichs im DATEV-Kontenrahmen. Fehlt wie `baseAccount`. |
| `rangeTo` | integer | Letztes vierstelliges Konto des Bereichs. Fehlt wie `baseAccount`. |
| `tax` | string | Umsatzsteuer eines Automatikkontos, die DATEV mitbucht, etwa `ust19%` (Umsatzsteuer 19 %) oder `v19%` (Vorsteuer 19 %). Fehlt, wenn die Steuer mit jeder Buchung kommt. |
| `updatedAt` | string (date-time) | Letzte Änderung. |

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