# Nachtrag zu einem Auftrag anlegen (https://developer.bimetrics.de/reference/sales/create-proposal-addendum)

`POST https://app.bimetrics.de/api/draft/{id}/proposal-addendum`

operationId: `createProposalAddendum` · Berechtigung (Scope): `invoices:draft` · Bereich: Ausgangsrechnungen

Legt wie „Nachtrag erstellen“ in der App einen Angebotsentwurf als Nachtrag zum Auftrag an: Kunde, Preisart und Steuerfall kommen aus dem Auftrag (seiner Auftragsbestätigung, sonst dem Angebot) und bleiben fest: Ein anderer Wert in updateDraft ergibt `400` mit `context.field` (`buyer`, `priceType`, `taxException`), unter § 13b UStG auch eine Position mit Umsatzsteuer (`items[i].taxRate`); Optionen gibt es nicht. Positionen gibt es noch keine, und der Kopftext nennt den Auftrag. Jeder Aufruf legt einen neuen Entwurf an. Das geht ab der Annahme des Angebots, bis die Schlussrechnung oder die Rechnung über den ganzen Auftrag ausgestellt ist: vorher `409 ProposalAddendumNotAccepted`, danach `409 ProposalAddendumOrderSettled`. Hat der Auftrag seitdem eine neue Auftragsbestätigung mit anderem Kopf bekommen, gibt das Ausstellen `409 ProposalAddendumOrderChanged`; dann einen neuen Nachtrag anlegen. Trägt der Auftrag § 19 und ist die Firma am Datum des Nachtrags kein Kleinunternehmer mehr, oder umgekehrt, gibt es keinen Nachtrag und keine neue Version davon (`409 ProposalAddendumTaxStatusChanged`). Beim Ausstellen bekommt der Nachtrag die nächste Angebotsnummer und seine Nummer im Auftrag (`proposalAddendum.number`); das PDF trägt die Überschrift „Nachtragsangebot“ und nennt den Auftrag. Beim Ausstellen gelten dieselben Regeln noch einmal, gemessen am Auftrag in diesem Moment. Danach bleibt das Angebot angenommen (`409 ProposalHasAddendum`), und eine Auftragsbestätigung lässt sich nicht mehr ausstellen (`409 OrderConfirmationAfterAddendum`). Ein Nachtrag wird mit `setProposalOutcome` beauftragt und zählt dann zum Auftragswert (`billing.value`); umwandeln lässt er sich nicht (`409 ProposalAddendumNotConvertible`). Die Route gibt es erst, wenn Nachträge freigeschaltet sind, vorher `404`. Idempotency-Key bei Wiederholung unverändert senden.

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 angenommenen Angebots oder seiner ausgestellten Auftragsbestätigung 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. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/draft/{id}/proposal-addendum" -X POST \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "Idempotency-Key: rechnung-2026-001"
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: Draft |
| 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 diesen Endpunkt (`APIKeyPermissionDenied`, `context.scope` nennt sie; Berechtigungen sind fest: neuen Schlüssel anlegen, austauschen, alten widerrufen), der Endpunkt ist für API-Schlüssel nicht freigegeben (`APIKeyPermissionDenied` ohne `context.scope`), 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 |
| 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 (`Draft`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `billing` | OrderBilling | Nur getDraft eines ausgestellten Angebots oder einer ausgestellten Auftragsbestätigung: Abrechnung des Auftrags mit Abschlägen, abschließender Rechnung und Summen. |
| `billingSummary` | BillingSummary | Nur filterDrafts, an ausgestelltem Angebot und ausgestellter Auftragsbestätigung: Kurzform von `billing`. |
| `companyId` | string (uuid) | ID der Firma. |
| `createdAt` | string (date-time) | Anlage in bimetrics. |
| `creatorUserCompanyId` | string (uuid) | ID der erstellenden Mitgliedschaft. |
| `deductedBy` | BillingRef | Nur ausgestellter Abschlag: die ausgestellte, nicht stornierte Schlussrechnung, die ihn abzieht. |
| `deletedAt` | string (date-time), kann null sein | Gilt als gelöscht seit diesem Zeitpunkt; `null`, solange nicht gelöscht. Gesetzt ist es nur in der Antwort von `deleteDraft` und `deleteOrderConfirmationDraft`; gelöschte Entwürfe liefert keine andere Route, auch `filterDrafts` mit `includeDeleted` nicht. |
| `documentId` | string (uuid), kann null sein | ID des ausgestellten Rechnungsbelegs; null bei offenem Entwurf. |
| `documentMail` | DocumentMailSummary | Nur in den Antworten von `getDraft` und `filterDrafts`. Die neueste Mail, mit der dieses Dokument über bimetrics gesendet wurde (aus der App, per API oder per MCP), samt Versandstand. Fehlt, wenn noch keine gesendet wurde. |
| `documentMatched` | boolean | Der ausgestellte Beleg ist bereits einer Zuordnung zugeordnet. |
| `downPaymentOrdinal` | integer | Nur Abschlag: seine Ordnungszahl im Auftrag, wie `ordinal` in `billing`. |
| `draftBody` | DraftBody | Gespeicherter Rechnungsinhalt. |
| `externalRef` | string | Externe Bestellreferenz. |
| `finalTotal` | integer | Bruttosumme des ausgestellten Belegs in Cent. |
| `id` | string (uuid) | ID des Entwurfs. |
| `invoiceCorrection` | InvoiceCorrectionInput | Quellgebundener Grund und Bruttokorrekturbeträge je Position. |
| `invoiceNumber` | string | Arbeitsnummer; nach Abschluss endgültige Rechnungsnummer. |
| `invoiceRole` | string: `down_payment`, `final` | Rolle der Rechnung im Auftrag: `down_payment` (Abschlag) oder `final` (Schlussrechnung), fest ab dem Ableiten; fehlt bei allen anderen Entwürfen. Filterbar in `filterDrafts`. |
| `kind` | string | Dokumentart invoice, proposal, order_confirmation, cancellation, invoice_correction oder correction_reversal. |
| `legacyProposalTotal` | boolean | Angebot vor dem 21.09.2026 ausgestellt: Summe je Zeile gerundet wie sein PDF. |
| `orderChanges` | string | Nur getDraft einer offenen Schlussrechnung, Rechnung über den ganzen Auftrag oder eines Abschlags: was sich am Auftrag seit dem Anlegen der Rechnung bzw. seit der letzten Berechnung des Abschlags geändert hat, etwa „Nachtrag 3 ist beauftragt, Nachtrag 1 ist nicht mehr beauftragt“ oder „Es gibt eine neue Auftragsbestätigung AB-2026-1004“. Fehlt, solange sich nichts geändert hat. Bis dahin lehnt finalizeDraft mit `409 ClosingInvoiceAddendaChanged` bzw. `409 DownPaymentOrderValueChanged` ab: Die Rechnung legst du mit `replaceDraftId` und `replaceExpectedUpdatedAt` neu an, den Abschlag speicherst du mit `downPayment` neu. Ein Auftrag ohne Nachtrag, auch ohne Entwurf eines Nachtrags, wird abgerechnet wie bisher. |
| `orderConfirmationId` | string (uuid), kann null sein | Ausgestellte Auftragsbestätigung; null bei offenem Entwurf. |
| `originalInvoiceId` | string (uuid), kann null sein | Originalentwurf für eine Stornorechnung; sonst null. |
| `originalTotal` | integer | Bruttosumme des Storno-Originals in Cent. |
| `payment` | DraftPayment | Zahlstand einer ausgestellten Rechnung (Typ 380); fehlt bei allen anderen Entwürfen. |
| `proposal` | DraftProposal | Ergebnis eines ausgestellten Angebots; fehlt bei allen anderen Entwürfen. |
| `proposalAddendum` | ProposalAddendum | Nur an einem Nachtrag (ausgestellt oder Entwurf): seine Nummer im Auftrag und der Auftrag. |
| `proposalVersion` | ProposalVersion | Versionen eines Angebots: am Entwurf einer neuen Version und an jedem ausgestellten Angebot mit mehr als einer Version; `versions` nur in getDraft. |
| `reversesCorrectionDocumentId` | string (uuid) | Ausgestellte Korrektur, die dieser Gegenbeleg aufhebt. |
| `salesProposalId` | string (uuid), kann null sein | ID eines erstellten Angebots, falls vorhanden. |
| `settledByFinalDraftId` | string (uuid) | Nur Storno oder Korrektur eines Abschlags: die Schlussrechnung, deren Ausstellen diesen Beleg erzeugt hat. |
| `source` | string | Zugang bei Anlage: web, api, mcp oder series für erzeugte Serienrechnungen. |
| `sourceInvoiceDocumentId` | string (uuid) | Unverändertes Original einer Rechnungskorrektur. |
| `sourceOrderConfirmationId` | string (uuid), kann null sein | Ausdrücklich gewählte finale AB als Rechnungsquelle; sonst null. |
| `sourceSalesProposalId` | string (uuid), kann null sein | Ursprüngliches Angebot, falls vorhanden. |
| `taxCase` | TaxCaseSnapshot | Beim Abschluss eingefrorener Steuerfall. |
| `typeCode` | string | EN-16931-Dokumenttyp: Rechnung 380, Rechnungskorrektur 381, Vollstorno oder Korrektur-Gegenbeleg 384. |
| `updatedAt` | string (date-time) | Letzte Änderung. |

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