# Neue Version eines Angebots anlegen (https://developer.bimetrics.de/reference/sales/create-proposal-version)

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

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

Legt wie „Neue Version erstellen“ in der App einen Angebotsentwurf mit allen Inhalten des Angebots an, mit heutigem Datum und so vielen Tagen Gültigkeit wie bisher. Das geht, solange das Angebot offen, abgelaufen oder abgelehnt ist und keine neuere ausgestellte Version hat. Gibt es schon einen offenen Entwurf dieser Version, kommt er zurück. Beim Ausstellen bekommt die neue Version die Nummer des ersten Angebots mit ihrer Version, etwa `AN-2026-1040-2`, und ihr PDF nennt unter dem Titel das Datum des ersetzten Angebots. Das ersetzte Angebot bleibt unverändert. Ein angenommenes Angebot ergibt `409 ProposalVersionAccepted`, eine neuere Version `409 ProposalVersionExists` (`context.version` und `context.draftId` nennen die neueste). Eine ersetzte Version lässt sich weder annehmen, ablehnen noch umwandeln (`409 ProposalReplaced`). Beim Ausstellen gelten dieselben Regeln noch einmal. 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 ausgestellten Angebots 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-version" -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
