# Rechnung, Korrektur, Angebot oder Auftragsbestätigung ausstellen (https://developer.bimetrics.de/reference/sales/finalize-draft)

`PUT https://app.bimetrics.de/api/draft/{id}/finalize`

operationId: `finalizeDraft` · Berechtigung (Scope): `invoices:finalize` · Bereich: Ausgangsrechnungen

Eine Auftragsbestätigung erhält eine eigene Nummer und ein PDF ohne XML oder Buchungen; das Ergebnis steht in orderConfirmation. Ein Angebot ebenso, mit Nummer aus dem Nummernkreis der Angebote; das Ergebnis steht in salesProposal. Rechnungen stehen weiterhin in document. Schließt genau den gespeicherten und mit expectedUpdatedAt bezeichneten Entwurf ab. Korrekturen und deren Gegenbelege erzeugen eigene unveränderliche Belege und entsprechende Buchungen; daraus entsteht keine Auszahlung. Bei Rechnungen wird die E-Rechnung geprüft und Rechnungsnummer, PDF, XML und Buchungsdaten erzeugt. Im Anfrageinhalt expectedUpdatedAt senden; für Korrekturen und deren Gegenbelege kann expectedCapacityRevision aus getCorrectionCapacity zusätzlich den geprüften Kapazitätsstand binden. Geänderte Kapazität erfordert dann eine erneute Prüfung. Eine Schlussrechnung storniert beim Ausstellen unbezahlte Abschläge des Auftrags und korrigiert teilbezahlte auf den bezahlten Betrag, in einem Schritt mit fortlaufenden Nummern; sind unbezahlte dabei, nur mit `acceptCancelOpenDownPayments`. `expectedSettlementRevision` bindet sie an die geprüften Abzüge (`409 FinalInvoicePaymentsChanged`). Gesperrt mit `409 DownPaymentDraftsOpen`, `409 DownPaymentPaymentUnknown`, `409 DownPaymentOverpaid`, `422 FinalInvoiceNegative`, `422 FinalInvoiceCashDiscount`. Keine bearbeitbaren Rechnungsfelder und kein Versand.

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

> **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 in dieser Firma (UUID). |
| `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 `FinalizeCommand`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `acceptCancelOpenDownPayments` | boolean | Nur Schlussrechnung: Zustimmung, dass das Ausstellen die unbezahlten Abschläge des Auftrags storniert oder auf 0 € korrigiert (`settlement.cancelled`, `settlement.corrected` und `settlement.acceptRequired` aus checkDraft). Ohne sie und mit solchen Abschlägen `422 OpenDownPaymentsNotAccepted`. |
| `expectedCapacityRevision` | string | Optional ausschließlich für Rechnungskorrekturen und deren Gegenbelege: unveränderte revision aus getCorrectionCapacity. Bindet die Ausgabe zusätzlich an die geprüfte Restkapazität; ein geänderter Stand liefert `409 VersionConflict` und erfordert erneute Prüfung. Bei anderen Belegarten weglassen. |
| `expectedSettlementRevision` | string | Nur Schlussrechnung, optional: `settlement.revision` aus checkDraft. Bindet das Ausstellen an die geprüften Abzüge; hat sich seither ein Zahlstand geändert, kommt `409 FinalInvoicePaymentsChanged`, dann neu prüfen. |
| `expectedUpdatedAt` | string (date-time), kann null sein | Exakter zuletzt gelesener updatedAt-Wert einschließlich Sekundenbruchteilen. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/draft/{id}/finalize" \
  -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`: FinalizeReturn |
| 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 |
| 402 | 110 % des Dokumentkontingents sind erreicht (`InvoiceQuotaExceeded`, mit `context.limit`, `context.usage` und `context.nextStep`). Nur bei Verträgen, die das vorsehen; der Entwurf bleibt unverändert, es wird keine Nummer vergeben. Nach einem Tarifwechsel erneut senden. | `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 |
| 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 ableiten, abschließen oder stornieren: Die Anschrift von Firma oder Kunde ist unvollständig (`InvoiceAddressRequired`, `context.field` ist `company.address`, `buyer.name` oder `buyer.address`), einer XRechnung fehlen Pflichtangaben (`XRechnungDataRequired`, `context.field` nennt die Angabe, etwa `buyerReference` oder `company.contactInfo.phone`), die Versteuerung der Firma ist nicht bestätigt (`SellerTaxStatusUnconfirmed`) oder ihre Steuernummer fehlt (`SellerTaxIdRequired`, bei Regelbesteuerung genügt die USt-IdNr.), beides nur in der App zu ergänzen, der Steuerfall hat ein blockierendes Problem (`TaxCaseInvalid`, mit `context.code`, `context.field` und `context.problems` wie bei der Entwurfsprüfung), die E-Rechnung besteht die Prüfung nicht (`InvoiceValidationFailed`), ein Abschlag oder eine Schlussrechnung geht für diesen Auftrag nicht (`DownPaymentTaxCaseUnsupported`, `DownPaymentTaxStatusChanged`, `DownPaymentBuyerChanged`, `DownPaymentSmallBusinessCashBasis`), oder beim Ausstellen einer Schlussrechnung fehlt die Zustimmung zu Stornos (`OpenDownPaymentsNotAccepted`), die Abzüge übersteigen die Leistung (`FinalInvoiceNegative`) oder Skonto geht nicht (`FinalInvoiceCashDiscount`). 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 (`FinalizeReturn`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `document` | Document | Ausgestellter Rechnungs-, Korrektur-, Gegen- oder Stornobeleg. |
| `orderConfirmation` | OrderConfirmation | Ausgestellte Auftragsbestätigung ohne Buchung oder XML. |
| `quotaNotice` | QuotaNotice | Nur bei einer Rechnung, nach der das Dokumentkontingent ausgeschöpft ist; die Rechnung ist trotzdem ausgestellt. |
| `salesProposal` | SalesProposal | Ausgestelltes Angebot ohne Buchung oder XML. |
| `warnings` | Array<TaxProblem> | Hinweise, die das Ausstellen nicht verhindert haben: `IssueDateBeforeLastInvoice`, wenn das Rechnungsdatum vor deiner letzten Rechnung liegt. Das ist erlaubt, fällt aber bei einer Betriebsprüfung auf. Fehlt ohne Hinweis und bei einer Wiederholung mit demselben Idempotency-Key. |

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