# Änderung einer Dauerbuchung prüfen (https://developer.bimetrics.de/reference/templates-and-recurring-bookings/preview-document-contract)

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

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

Sagt, was Anlegen, Ändern, Beenden oder Löschen mit den Periodenbelegen täte, und ändert nichts. Gerechnet wird wie beim Speichern, Ablehnungen sind dieselben. `action` ist `create`, `update`, `end` oder `delete`; außer bei `create` nennt `id` die Dauerbuchung. `end` nennt bei `action` `end` das neue Ende: Es darf nie verlängern (`422 DocumentContractEndExtends`). `pastDocuments` gilt bei `delete`.

Benötigt einen Schlüssel mit der Berechtigung `collections:write`.

> **Achtung:** Dieser Aufruf ist nicht als rein lesend gekennzeichnet und kann echte Daten in der Firma anlegen oder ändern. Es gibt keine Testumgebung.
>
> KI-Agenten fragen vor diesem Aufruf beim Nutzer nach.

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Request-Body (`application/json`)

 

Schema `DocumentContractPreviewRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `action` | string | `create`, `update`, `end` oder `delete`. |
| `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. |
| `end` | NaiveDate | Neues ausschließliches Ende bei `action` `end`. |
| `expectedUpdatedAt` | string (date-time) | `updatedAt` des gelesenen Objekts, beim Ändern Pflicht. |
| `friendlyName` | string, kann null sein | Bezeichnung. |
| `id` | string (uuid) | ID der Dauerbuchung; außer bei `create` Pflicht. |
| `issuer` | DocumentIssuer | Aussteller: die Gegenpartei bei `receipt`. |
| `kind` | string, kann null sein | `invoice` (Ausgangsrechnung) oder `receipt` (Eingangsbeleg), ohne Angabe beim Anlegen `receipt`. |
| `pastDocuments` | boolean | Bei `delete`: auch die Belege bis heute. |
| `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/preview" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"and","children":[],"limit":50,"offset":0}'
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: DocumentContractPlan |
| 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 |
| 404 | Nicht gefunden (`NotFound`). | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 422 | Das neue Ende verlängert die Dauerbuchung (`DocumentContractEndExtends`) oder endet vor der laufenden Periode (`DocumentContractEndBeforeRunningPeriod`). Ein anderes Ende wählen statt wiederholen. | `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 (`DocumentContractPlan`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `action` | string | Die geprüfte Aktion. |
| `amountPerPeriodMinor` | integer | Betrag je ganzer Periode in Cent. |
| `contractId` | string (uuid) | ID der Dauerbuchung; fehlt bei `create`. |
| `contractStays` | boolean | Beim Löschen: Weil Belege bleiben, bleibt auch die Dauerbuchung als gelöscht vermerkt. |
| `creates` | Array<DocumentContractPeriod>, kann null sein | Neue Belege mit Buchung, auch für vergangene Perioden. |
| `deletes` | Array<DocumentContractPeriod>, kann null sein | Belege, die entfallen. |
| `keeps` | Array<DocumentContractPeriod>, kann null sein | Belege, die bleiben, wie sie sind: zugeordnet, bezahlt, festgeschrieben oder beim Löschen ohne `pastDocuments` aus der Zeit bis heute. |
| `pastPeriods` | integer | Wie viele der neuen Belege abgelaufene Perioden betreffen. |
| `rewrites` | Array<DocumentContractPeriod>, kann null sein | Offene Belege, die die neuen Zeilen übernehmen. |
| `unchanged` | integer | Offene Belege, die sich nicht ändern. |
| `updatedAt` | string (date-time) | Stand der Dauerbuchung; fehlt bei `create`. |

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