Rechnungs- oder AB-Entwurf ändern
Benötigte Berechtigung:invoices:draft(Rechnungsentwürfe verwalten)
Echte Wirkung
/api/draft/{id}Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Speichert den vollständigen Entwurfsinhalt mit expectedUpdatedAt. Abgeschlossene Entwürfe können nicht geändert werden. Korrekturentwürfe ausschließlich über updateInvoiceCorrection ändern.
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
Vollständiger Ersatz eines offenen Entwurfs mit Versionsprüfung.
acceptStandardVatWithoutVatId?booleanBewusste Bestätigung deutscher Umsatzsteuer bei EU-Unternehmer ohne gültige USt-IdNr.
acceptUnverifiedVatId?booleanBestätigung einer USt-IdNr., die VIES als ungültig abgelehnt hat. Die API setzt sie nicht neu (400, VatIdConfirmationNotAllowed); eine gespeicherte Bestätigung darf unverändert zurückkommen, false nimmt sie zurück.
buyer?Rechnungsempfänger; für bestehende Kontakte contactId verwenden.
buyerReference?stringKäuferreferenz (BT-10), bei öffentlichen Auftraggebern die Leitweg-ID; Pflicht bei XRECHNUNG, ohne Angabe mit buyer.contactId die Leitweg-ID des Kontakts; höchstens 100 Zeichen.
cashDiscount?Skontobedingungen.
costCenterId?stringID der Kostenstelle oder Verteilung für die Rechnung. Auf dem Rechnungsdokument erscheint sie nicht. Bei Angeboten und Auftragsbestätigungen übernimmt die Rechnung sie beim Umwandeln. Ein leerer String heißt ausdrücklich: keine. Fehlt das Feld, bekommt die Rechnung beim Ausstellen die Kostenstelle des Kunden; ein PUT ohne das Feld löscht also eine zuvor gewählte. Storno und Korrektur übernehmen die Kostenstelle des Originals, Serienrechnungen die des Kunden. Bei einer unbekannten oder fremden ID scheitert das Ausstellen mit 404 CostCenterNotFound, bei einer archivierten mit 409 CostCenterRejected.
currency?stringWährung; ausschließlich EUR.
delivery?Abweichende Lieferdaten.
downPayment?Nur Abschlag: neue Höhe, percent oder amountMinor wie bei deriveSalesDocument. Damit baut bimetrics Positionen und Preisart aus dem Auftrag neu; gesendete items zählen nicht, Handänderungen gehen verloren. Das gilt auch, wenn du das gelesene downPayment unverändert zurückschickst. Ohne downPayment gelten items wie gesendet. An anderen Belegen 400 mit context.field downPayment.
dueDate?|Fälligkeitsdatum. Fehlen beim Anlegen einer Rechnung dueDate und cashDiscount, nimmt sie die eigenen Bedingungen des Kunden aus buyer (paymentTerms am Kontakt).
einvoiceProfile?stringProfil der E-Rechnung: EN16931 (Standard) oder XRECHNUNG; EXTENDED nur in der App.
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. Leer, solange es noch nicht feststeht.
expectedUpdatedAt?|Exakter zuletzt gelesener updatedAt-Wert; bei Konflikt aktuellen Entwurf neu prüfen.
date-timeexternalRef?stringExterne Bestellreferenz, höchstens 200 Zeichen.
issueDate?Rechnungsdatum.
items?array<>|Rechnungspositionen mit Menge, Preis und Steuersatz.
layoutId?stringLayout modern oder classic, am besten weglassen: Ein neuer Entwurf übernimmt dann das Layout, das gerade gilt, eine Änderung behält das des Entwurfs. Sobald Layouts im Layout-Editor gewählt werden, antwortet bimetrics auf jeden anderen Wert mit 400 und dem Code layout_choice_moved.
"modern""classic"notes?stringFußtext unter der Summe; beim Anlegen leer: die Textvorlage der Firma, sonst der Standardtext der App.
orderReference?stringBestellnummer des Kunden (BT-13); höchstens 100 Zeichen.
orderRevision?Nur Schlussrechnung, Rechnung über den ganzen Auftrag und Abschlag: der Stand des Auftrags, aus dem die Rechnung angelegt bzw. der Abschlag zuletzt berechnet wurde. Nur bimetrics setzt es, ein gesendeter Wert zählt nicht.
performancePeriodFrom?Beginn des Leistungszeitraums.
performancePeriodTo?Ende des Leistungszeitraums.
priceType?stringPreisart net oder gross für die Positionspreise.
reference?stringBezug auf die Vorgängerrechnung oder das Angebot; in der E-Rechnung nur bei Storno und Korrektur.
remark?stringKopftext über den Positionen; beim Anlegen leer: die Textvorlage der Firma, sonst der Standardtext der App.
retention?Nur Rechnung und Abschlag: Sicherheitseinbehalt. Rechnungsbetrag, Umsatzsteuer und der fällige Betrag der E-Rechnung bleiben; die Zahlungsbedingungen nennen den Einbehalt, und er wird erst an dueOn fällig. Probleme meldet die Prüfung mit Codes retention_…, das Ausstellen dann mit 422 RetentionInvalid. An anderen Belegen 400 mit context.field retention.
showQRCode?booleanQR-Code auf dem Rechnungsdokument anzeigen.
strict?booleanLegacy-Feld; die fachliche Validierung beim Abschluss ist immer aktiv.
supplierNumber?stringLieferantennummer beim Kunden (BT-29); höchstens 100 Zeichen.
taxException?Manuell gewählter zulässiger Steuer-Ausnahmefall. Mit § 13b oder § 4 speichert bimetrics jede Position mit 0 % und merkt sich ihren Satz; ohne Ausnahme bekommt eine Rechnungsposition mit 0 % ihren Satz zurück, solange sie an derselben Stelle mit demselben Namen und derselben Beschreibung bleibt und der Kunde in Deutschland sitzt; bei Kunden im Ausland bleibt 0 %.
taxHintText?stringAbweichender Steuerhinweis für diesen Entwurf.
taxRateReason?stringSteuerbegründung als Kennung, leer im normalen Steuerfall.
validUntil?|Gültigkeitsende; für Angebote reserviert.
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" \ -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": "invoice", "orderConfirmationId": null, "originalInvoiceId": null, "salesProposalId": null, "source": "api", "sourceOrderConfirmationId": null, "sourceSalesProposalId": null, "typeCode": "380", "updatedAt": "2026-09-01T08:01:02.123456Z"}Offenen Entwurf löschen DELETE
Löscht einen offenen Entwurf einer Rechnung, Stornorechnung, eines Angebots oder einer Auftragsbestätigung, wie „Löschen“ in der App. `expectedUpdatedAt` muss der gelesenen Version entsprechen. Es wird keine Nummer verbraucht, nichts gebucht und nichts versendet. Ausgestellte Belege bleiben geschützt (`409 DraftFinalized`); sie werden korrigiert oder storniert. Entwürfe von Rechnungskorrekturen und ihren Gegenbelegen löscht nur die App (`403`). Idempotency-Key bei Wiederholung unverändert senden. Benötigt einen Schlüssel mit der Berechtigung `invoices:draft`.
Ausgangsrechnung vollständig stornieren POST
Erstellt einen Vollstorno vom Typ 384 aus der serverseitigen Originalvorlage. expectedUpdatedAt bezeichnet den Originalentwurf. Keine freie Gutschrift und kein Versand. Benötigt einen Schlüssel mit der Berechtigung `invoices:finalize`.