# Kostenstelle oder Verteilung anlegen (https://developer.bimetrics.de/reference/cost-centers/create-cost-center)

`POST https://app.bimetrics.de/api/cost-centers`

operationId: `createCostCenter` · Berechtigung (Scope): `company:write` · Bereich: Kostenstellen

Legt eine Kostenstelle (`kind` `center`, mit `code` und `name`) oder eine Verteilung an (`kind` `distribution`, mit `name` und `shares`), wie in den Einstellungen der App. Die Nummer ist die KOST1 im DATEV-Export: 1 bis 8 Ziffern ohne führende Null oder 1 bis 8 Buchstaben ohne Umlaute, je Firma eindeutig, auch gegenüber archivierten, ohne Unterschied zwischen Groß- und Kleinschreibung. Die Steuerberatung muss sie in DATEV genauso anlegen, sonst führt DATEV die Buchungen als „nicht berücksichtigt“. Eine Verteilung braucht mindestens zwei verschiedene Kostenstellen, die nicht archiviert sind, und ihre Anteile ergeben zusammen 10000 Basispunkte (100 %). Verstößt die Anfrage gegen eine Regel, antwortet die Route mit `400 CostCenterRejected`, `context.field` nennt das Feld und `context.message` den Satz der App; eine vergebene Nummer ergibt `409 CostCenterRejected`. 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`)

cost center or distribution

Schema `CostCenterRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `code` | string | Nur bei einer Kostenstelle: die KOST1 im DATEV-Export, 1 bis 8 Ziffern ohne führende Null oder 1 bis 8 Buchstaben ohne Umlaute, je Firma eindeutig. Fehlt bei einer Verteilung. |
| `expectedUpdatedAt` | string (date-time) | Nur beim Ändern: das zuletzt gelesene `updatedAt`, unverändert mit allen Nachkommastellen. Für API-Schlüssel Pflicht. |
| `kind` | string: `center`, `distribution` | Beim Anlegen Pflicht: `center` für eine Kostenstelle, `distribution` für eine Verteilung. Beim Ändern ohne Wirkung. |
| `name` | string | Name, höchstens 60 Zeichen, etwa „Standort Nord“. |
| `shares` | Array<CostCenterShare> | Nur bei einer Verteilung: die Kostenstellen mit ihren Anteilen, zusammen 10000 Basispunkte. Fehlt bei einer Kostenstelle. |

### Beispiel

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

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `archivedAt` | string (date-time) | Archiviert seit diesem Zeitpunkt: lässt sich nicht mehr auswählen, Belege behalten sie. Fehlt, solange aktiv. |
| `code` | string | Nur bei einer Kostenstelle: die KOST1 im DATEV-Export, 1 bis 8 Ziffern ohne führende Null oder 1 bis 8 Buchstaben ohne Umlaute, je Firma eindeutig. Fehlt bei einer Verteilung. |
| `companyId` | string (uuid) | ID der Firma. |
| `createdAt` | string (date-time) | Anlage in bimetrics. |
| `documents` | integer | Zahl der Belege, die sie tragen, ohne gelöschte. |
| `id` | string (uuid) | ID der Kostenstelle oder Verteilung. |
| `kind` | string: `center`, `distribution` | `center` für eine Kostenstelle, `distribution` für eine Verteilung. |
| `name` | string | Name, höchstens 60 Zeichen, etwa „Standort Nord“. |
| `shares` | Array<CostCenterShare> | Nur bei einer Verteilung: die Kostenstellen mit ihren Anteilen, zusammen 10000 Basispunkte. Fehlt bei einer Kostenstelle. |
| `updatedAt` | string (date-time) | Letzte Änderung. |
| `used` | boolean | `true`, sobald ein Beleg oder eine Buchung sie trägt, auch über eine Verteilung oder bei einem gelöschten Beleg mit Buchungen. Dann stehen Nummer und Anteile fest. |

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