Folgedokument aus gewählter Quelle erstellen
Benötigte Berechtigung:invoices:draft(Rechnungsentwürfe verwalten)
Echte Wirkung
/api/draft/{id}/deriveKein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
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, aus einem Nachtrag 409 ProposalAddendumNotConvertible, eine Auftragsbestätigung nach einem ausgestellten Nachtrag 409 OrderConfirmationAfterAddendum. 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.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
id*stringID des Objekts in dieser Firma (UUID).
uuidIdempotency-Key*stringStabiler 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.
^[!-~]+$1 <= length <= 128application/json- body
Bewusst gewählte Ableitung aus einem finalisierten Quellentwurf.
amountMinor?integerNur Abschlag: Betrag in Cent in der Preisart des Auftrags (netto oder brutto, priceType der Quelle), über 0.
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?|Unverändert gelesener updatedAt-Wert des Quellentwurfs.
date-timeinvoiceRole?stringdown_payment für eine Abschlagsrechnung, final für die Schlussrechnung, nur mit targetKind invoice. Ohne: Rechnung über den ganzen Auftrag.
"down_payment""final"percent?stringNur Abschlag: Prozent der festen Positionen des Auftrags und seiner beauftragten Nachträge ohne Auslagen, über 0 bis 100, höchstens zwei Nachkommastellen, als Zeichenfolge. Genau eins von percent und amountMinor.
^-?[0-9]+(\.[0-9]+)?$decimalreplaceDraftId?stringNur Schlussrechnung und Rechnung über den ganzen Auftrag: die offene Rechnung desselben Auftrags und derselben Art, die die neue ersetzt, etwa nach 409 ClosingInvoiceAddendaChanged. bimetrics löscht sie im selben Schritt; scheitert das Ableiten, bleibt sie. Änderungen an ihr gehen verloren; der Verlauf der neuen nennt die ersetzte. Sonst 400 mit context.field replaceDraftId.
uuidreplaceExpectedUpdatedAt?stringPflicht mit replaceDraftId: ihr zuletzt gelesener updatedAt. Hat sie sich seitdem geändert, 409 VersionConflict, und nichts geschieht.
date-timeselectedLines?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?stringorder_confirmation aus finalem Angebot oder invoice aus finalem Angebot oder finaler Auftragsbestätigung.
"order_confirmation""invoice"Erfolg.
application/json- response
Offener oder abgeschlossener Rechnungsentwurf mit Version und Referenz zum ausgestellten Beleg.
billing?Nur getDraft eines ausgestellten Angebots oder einer ausgestellten Auftragsbestätigung: Abrechnung des Auftrags mit Abschlägen, abschließender Rechnung und Summen.
billingSummary?Nur filterDrafts, an ausgestelltem Angebot und ausgestellter Auftragsbestätigung: Kurzform von billing.
companyId?stringID der Firma.
uuidcreatedAt?stringAnlage in bimetrics.
date-timecreatorUserCompanyId?stringID der erstellenden Mitgliedschaft.
uuiddeductedBy?Nur ausgestellter Abschlag: die ausgestellte, nicht stornierte Schlussrechnung, die ihn abzieht.
deletedAt?|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.
date-timedocumentId?|ID des ausgestellten Rechnungsbelegs; null bei offenem Entwurf.
uuiddocumentMail?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?booleanDer ausgestellte Beleg ist bereits einer Zuordnung zugeordnet.
downPaymentOrdinal?integerNur Abschlag: seine Ordnungszahl im Auftrag, wie ordinal in billing.
draftBody?Gespeicherter Rechnungsinhalt.
externalRef?stringExterne Bestellreferenz.
finalTotal?integerBruttosumme des ausgestellten Belegs in Cent.
id?stringID des Entwurfs.
uuidinvoiceCorrection?Quellgebundener Grund und Bruttokorrekturbeträge je Position.
invoiceNumber?stringArbeitsnummer; nach Abschluss endgültige Rechnungsnummer.
invoiceRole?stringRolle der Rechnung im Auftrag: down_payment (Abschlag) oder final (Schlussrechnung), fest ab dem Ableiten; fehlt bei allen anderen Entwürfen. Filterbar in filterDrafts.
"down_payment""final"kind?stringDokumentart invoice, proposal, order_confirmation, cancellation, invoice_correction oder correction_reversal.
legacyProposalTotal?booleanAngebot vor dem 21.09.2026 ausgestellt: Summe je Zeile gerundet wie sein PDF.
orderChanges?stringNur 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?|Ausgestellte Auftragsbestätigung; null bei offenem Entwurf.
uuidoriginalInvoiceId?|Originalentwurf für eine Stornorechnung; sonst null.
uuidoriginalTotal?integerBruttosumme des Storno-Originals in Cent.
payment?Zahlstand einer ausgestellten Rechnung (Typ 380); fehlt bei allen anderen Entwürfen.
proposal?Ergebnis eines ausgestellten Angebots; fehlt bei allen anderen Entwürfen.
proposalAddendum?Nur an einem Nachtrag (ausgestellt oder Entwurf): seine Nummer im Auftrag und der Auftrag.
proposalVersion?Versionen eines Angebots: am Entwurf einer neuen Version und an jedem ausgestellten Angebot mit mehr als einer Version; versions nur in getDraft.
reversesCorrectionDocumentId?stringAusgestellte Korrektur, die dieser Gegenbeleg aufhebt.
uuidsalesProposalId?|ID eines erstellten Angebots, falls vorhanden.
uuidsettledByFinalDraftId?stringNur Storno oder Korrektur eines Abschlags: die Schlussrechnung, deren Ausstellen diesen Beleg erzeugt hat.
uuidsource?stringZugang bei Anlage: web, api, mcp oder series für erzeugte Serienrechnungen.
sourceInvoiceDocumentId?stringUnverändertes Original einer Rechnungskorrektur.
uuidsourceOrderConfirmationId?|Ausdrücklich gewählte finale AB als Rechnungsquelle; sonst null.
uuidsourceSalesProposalId?|Ursprüngliches Angebot, falls vorhanden.
uuidtaxCase?Beim Abschluss eingefrorener Steuerfall.
typeCode?stringEN-16931-Dokumenttyp: Rechnung 380, Rechnungskorrektur 381, Vollstorno oder Korrektur-Gegenbeleg 384.
updatedAt?stringLetzte Änderung.
date-timecurl --fail-with-body "https://app.bimetrics.de/api/draft/497f6eca-6276-4993-bfeb-53cbbbba6f08/derive" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "createdAt": "2026-09-01T08:00:00Z", "creatorUserCompanyId": "53cd10a9-c864-4dc3-a777-9860d59efe6c", "deletedAt": null, "documentId": null, "draftBody": { "buyer": { "address": { "city": "Hamburg", "countryId": "DE", "line1": "Am Hafen 12", "postcode": "20457" }, "contactId": "b17e8812-eae4-49b6-b5dc-30510635cb07", "customerNumber": 1004, "email": "", "name": "Brauhaus Elbwiese GmbH", "vatId": "" }, "dueDate": { "day": 15, "month": 9, "year": 2026 }, "issueDate": { "day": 1, "month": 9, "year": 2026 }, "items": [ { "description": "Gestaltung einer Geschäftsausstattung", "discount": "0", "name": "Gestaltung", "position": "1", "quantity": "1", "taxRate": "19", "unit": "C62", "unitPrice": "100" } ], "notes": "", "performancePeriodFrom": { "day": 1, "month": 9, "year": 2026 }, "priceType": "net", "remark": "", "showQRCode": false, "strict": false, "taxRateReason": "none", "validUntil": null }, "externalRef": "order-2026-1042", "id": "821c3664-640a-4e10-b120-a4ff713532f8", "invoiceNumber": "Entwurf 1042", "kind": "order_confirmation", "orderConfirmationId": null, "originalInvoiceId": null, "salesProposalId": null, "source": "api", "sourceOrderConfirmationId": null, "sourceSalesProposalId": "821c3664-640a-4e10-b120-a4ff713532f8", "typeCode": "380", "updatedAt": "2026-09-01T08:01:02.123456Z"}Ausgestellte Rechnungskorrektur vollständig aufheben POST
Erstellt und stellt einen positiven Gegenbeleg correction_reversal zur ausdrücklich gewählten Korrektur aus. Die ursprüngliche Rechnung und beide Korrekturbelege bleiben erhalten. Erzeugt Gegenbuchungen, keine Auszahlung oder Abbuchung. expectedUpdatedAt bezeichnet den ausgestellten Korrekturentwurf. Benötigt einen Schlüssel mit der Berechtigung `invoices:finalize`.
Ausgestellte E-Rechnung laden GET
Liefert das bereits ausgestellte CII-XML einer abgeschlossenen Rechnung, Stornorechnung, Rechnungskorrektur oder deren Gegenbeleg als Datei. Die Bytes stammen aus dem unveränderten ausgestellten PDF. Benötigt einen Schlüssel mit der Berechtigung `sales:read` oder `read`.