# Genau eine Rechnungsperiode erzeugen (https://developer.bimetrics.de/reference/recurring-invoices/prepare-recurring-invoice)

`POST https://app.bimetrics.de/api/recurringinvoice/{id}/prepare`

operationId: `prepareRecurringInvoice` · Berechtigung (Scope): `invoices:draft` · Bereich: Wiederkehrende Rechnungen

Manueller Aufruf für eine gültige Periode, auch bei pausierter Vorlage oder einem zukünftigen Termin. Im gespeicherten Modus draft entsteht ein Entwurf ohne finale Nummer oder Buchung. issue benötigt zusätzlich invoices:finalize und stellt die Rechnung mit Originaldatei und Buchungen aus. run.documentId verweist dann auf den ausgestellten Beleg; draft enthält den finalen Rechnungsstand. Wiederholungen liefern denselben ursprünglichen run, auch nach Moduswechsel. Wurde ein ursprünglicher Entwurf gelöscht, fehlt draft; kein Ersatz und keine nachträgliche Ausstellung. Eine gescheiterte Rechnungsprüfung antwortet mit 422; die Periode bleibt dann unverbraucht. Kein Versand.

Benötigt einen Schlüssel mit der Berechtigung `invoices:draft`.

> **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 des Objekts dieser Firma (UUID); bei Forderungsständen und neuen Korrekturen die Quellentwurfs-ID. |
| `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 `PrepareRecurringInvoice`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `expectedUpdatedAt` | string (date-time), kann null sein | Aktuelle Version der Serienvorlage. |
| `periodDate` | string | Gültiger Kalendertermin YYYY-MM-DD gemäß gespeichertem Plan, auch zukünftig erlaubt. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/recurringinvoice/{id}/prepare" \
  -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`: PreparedRecurringInvoice |
| 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 aktiven Tarif mit API-Zugang, etwa in der Testphase oder nach Ende 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 |
| 422 | Die Rechnung lässt sich so nicht abschließen oder stornieren: Die Anschrift von Firma oder Kunde ist unvollständig (`InvoiceAddressRequired`, `context.field` ist `company.address`, `buyer.name` oder `buyer.address`), der Steuerfall hat ein blockierendes Problem (`TaxCaseInvalid`, mit `context.code`, `context.field` und `context.problems` wie bei der Entwurfsprüfung), oder die E-Rechnung besteht die Prüfung nicht (`InvoiceValidationFailed`). Entwurf oder Stammdaten korrigieren 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 (`PreparedRecurringInvoice`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `draft` | Draft | Erzeugter bzw. bereits vorhandener Rechnungsstand, bei issue mit documentId final ausgestellt; fehlt, falls ein offener Entwurf später aktiv gelöscht wurde. Kein zweiter Entwurf und keine nachträgliche Ausstellung früherer Läufe. |
| `run` | RecurringInvoiceRun | Dauerhafter eindeutiger Periodennachweis mit generationMode und gegebenenfalls documentId. |

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