# Dauerbuchung anlegen (https://developer.bimetrics.de/reference/templates-and-recurring-bookings/create-document-contract)

`POST https://app.bimetrics.de/api/document/collection/contract/`

operationId: `createDocumentContract` · Berechtigung (Scope): `collections:write` · Bereich: Vorlagen und Dauerbuchungen

Legt eine Dauerbuchung an, wie in der App: Für jede Periode entsteht sofort ein Beleg mit Buchung, auch für vergangene. `POST /api/document/collection/contract/preview` zeigt das vorher. Der Rhythmus ist 1, 3, 6 oder 12 Monate, `end` gilt ausschließlich und liegt nach `start`. Zeilen haben einen festen Betrag. Geprüft wird wie im Formular der App: Bezeichnung, Art `invoice` oder `receipt`, 1 bis 100 Zeilen mit Betrag oder Anteil, Kategorie passend zu Art, Verwendung und Kontenrahmen, Steuersatz 19, 7 oder 0 %, auf Eingangsbelegen auch 9 oder 5,5 %, soweit die Kategorie ihn zulässt, Steuerfall bei 0 % auf Eingangsbelegen und die Gegenpartei der Art, außer alle Kategorien werden direkt gebucht. Verstöße ergeben `400 InvalidBookkeepingChange` mit `context.field`. Bezeichnung, Kategorie und Steuersatz werden nur geprüft, wenn sie neu sind. Eine Wiederholung mit gleichem Idempotency-Key wirkt nicht doppelt.

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

 

Schema `DocumentCollectionWrite`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `collectionNumber` | string, kann null sein | Nummer; wird zur Rechnungsnummer der erzeugten Belege. |
| `costCenterId` | string | Kostenstelle oder Verteilung aller Belege der Dauerbuchung als ID, ein leerer String entfernt sie. Eine Änderung gilt für künftige Belege und für alle, die noch nicht festgeschrieben, zugeordnet oder bezahlt sind. Ohne Angabe bleibt sie. |
| `documentContractRepetitionFixed` | DocumentContractRepetitionFixed | Nur bei Dauerbuchungen: Beginn, ausschließliches Ende und Rhythmus. |
| `expectedUpdatedAt` | string (date-time) | `updatedAt` des gelesenen Objekts, beim Ändern Pflicht. |
| `friendlyName` | string, kann null sein | Bezeichnung. |
| `issuer` | DocumentIssuer | Aussteller: die Gegenpartei bei `receipt`. |
| `kind` | string, kann null sein | `invoice` (Ausgangsrechnung) oder `receipt` (Eingangsbeleg), ohne Angabe beim Anlegen `receipt`. |
| `positionTemplate` | Array<DocumentPositionTemplate>, kann null sein | Die Zeilen, 1 bis 100. Ersetzt beim Ändern alle Zeilen. |
| `recipient` | DocumentRecipient | Empfänger: die Gegenpartei bei `invoice`. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/document/collection/contract/" \
  -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`: DocumentContract |
| 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 (`DocumentContract`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `collectionNumber` | string | Nummer der Dauerbuchung; wird zur Rechnungsnummer (`invoiceNumber`) der erzeugten Belege. Ist sie leer, entsteht die Rechnungsnummer aus der Bezeichnung. |
| `companyId` | string (uuid) | ID der Firma. |
| `costCenterId` | string (uuid) | Kostenstelle oder Verteilung als ID; fehlt ohne. |
| `createdAt` | string (date-time) | Anlage in bimetrics. |
| `documentContractRepetitionFixed` | DocumentContractRepetitionFixed | Zeitraum und Rhythmus der erzeugten Belege. |
| `friendlyName` | string | Bezeichnung. |
| `id` | string (uuid) | ID der Dauerbuchung. |
| `issuer` | DocumentIssuer | Aussteller der erzeugten Belege. |
| `kind` | string: `invoice`, `receipt` | Belegart der erzeugten Belege: `invoice` oder `receipt`. |
| `positionTemplate` | Array<DocumentPositionTemplate>, kann null sein | Vorlagen der Positionen der erzeugten Belege. |
| `recipient` | DocumentRecipient | Empfänger der erzeugten Belege. |
| `updatedAt` | string (date-time) | Letzte Änderung. |
| `uploadDocument` | UploadDocument | Die hinterlegte Datei; `null` ohne Datei. |
| `uploadDocumentId` | string (uuid), kann null sein | ID einer hinterlegten Datei; `null` ohne Datei. |

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