# Folgedokument aus gewählter Quelle erstellen (https://developer.bimetrics.de/reference/sales/derive-sales-document)

`POST https://app.bimetrics.de/api/draft/{id}/derive`

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

Mit targetKind order_confirmation entsteht aus einem finalisierten Angebot eine optionale Auftragsbestätigung als Entwurf. Mit targetKind invoice entsteht ausdrücklich aus dem finalisierten Angebot oder der finalisierten Auftragsbestätigung eine Rechnung. expectedUpdatedAt bezeichnet den gelesenen Quellentwurf. Das Original bleibt unverändert. Je Auftrag höchstens eine gültige Rechnung über den ganzen Auftrag oder eine Schlussrechnung; nach einem Storno ist wieder eine möglich. Davor beliebig viele Abschläge (`invoiceRole`). Sperren: `409 FinalInvoiceExists`, `409 DownPaymentsExist`, `422 DownPaymentTaxCaseUnsupported`. Kein Versand und keine Buchung beim Ableiten. Setzt ein Angebot automatisch auf angenommen, auch nach einer Ablehnung.

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 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 `DeriveCommand`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `amountMinor` | integer | Nur Abschlag: Betrag in Cent in der Preisart des Auftrags (netto oder brutto, `priceType` der Quelle), über 0. |
| `expectedPerformance` | ExpectedPerformance | Nur Abschlag: wann der ganze Auftrag voraussichtlich fertig ist, am Bau die Abnahme, auch wenn Teile schon erledigt sind. `from` und `to` als Tag, ein Monat vom ersten bis letzten Tag. Weglassen, wenn es noch nicht feststeht; aus einer Auftragsbestätigung belegt bimetrics den vereinbarten Zeitraum vor, außer er ist vorbei. |
| `expectedUpdatedAt` | string (date-time), kann null sein | Unverändert gelesener updatedAt-Wert des Quellentwurfs. |
| `invoiceRole` | string: `down_payment`, `final` | `down_payment` für eine Abschlagsrechnung, `final` für die Schlussrechnung, nur mit `targetKind` `invoice`. Ohne: Rechnung über den ganzen Auftrag. |
| `percent` | string (decimal) | Nur Abschlag: Prozent der festen Positionen des Auftrags ohne Auslagen, über 0 bis 100, höchstens zwei Nachkommastellen, als Zeichenfolge. Genau eins von `percent` und `amountMinor`. |
| `selectedLines` | Array<integer> | Die beauftragten optionalen Positionen als Index in items der Quelle, ab 0. Sie werden normale Positionen, eine gewählte Alternative ersetzt ihre feste Position, je feste Position höchstens eine. Ohne Angabe kommen nur die festen Positionen mit. |
| `targetKind` | string: `order_confirmation`, `invoice` | order_confirmation aus finalem Angebot oder invoice aus finalem Angebot oder finaler Auftragsbestätigung. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/draft/{id}/derive" \
  -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`: 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 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 (`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. |
| `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. |
| `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
