Nachtrag zu einem Auftrag anlegen
Benötigte Berechtigung:invoices:draft(Rechnungsentwürfe verwalten)
Echte Wirkung
/api/draft/{id}/proposal-addendumKein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
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.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
id*stringID des angenommenen Angebots oder seiner ausgestellten Auftragsbestätigung 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 <= 128Erfolg.
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/proposal-addendum" -X POST \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001"{ "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": "EN-2026-0061", "kind": "proposal", "orderConfirmationId": null, "originalInvoiceId": null, "proposalAddendum": { "number": 2, "orderId": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b", "orderIssueDate": { "day": 10, "month": 11, "year": 2026 }, "orderKind": "order_confirmation", "orderNumber": "AB-2026-0012", "proposalId": "7c3e9a21-4b6d-4f8e-a1c2-3d4e5f6a7b8c" }, "salesProposalId": null, "source": "api", "sourceOrderConfirmationId": null, "sourceSalesProposalId": null, "typeCode": "", "updatedAt": "2026-09-01T08:01:02.123456Z"}Rechnung, Korrektur, Angebot oder Auftragsbestätigung ausstellen PUT
Eine Auftragsbestätigung erhält eine eigene Nummer und ein PDF ohne XML oder Buchungen; das Ergebnis steht in orderConfirmation. Ein Angebot ebenso, mit Nummer aus dem Nummernkreis der Angebote; das Ergebnis steht in salesProposal. Rechnungen stehen weiterhin in document. Schließt genau den gespeicherten und mit expectedUpdatedAt bezeichneten Entwurf ab. Korrekturen und deren Gegenbelege erzeugen eigene unveränderliche Belege und entsprechende Buchungen; daraus entsteht keine Auszahlung. Bei Rechnungen wird die E-Rechnung geprüft und Rechnungsnummer, PDF, XML und Buchungsdaten erzeugt. Im Anfrageinhalt expectedUpdatedAt senden; für Korrekturen und deren Gegenbelege kann expectedCapacityRevision aus getCorrectionCapacity zusätzlich den geprüften Kapazitätsstand binden. Geänderte Kapazität erfordert dann eine erneute Prüfung. Eine Schlussrechnung storniert beim Ausstellen unbezahlte Abschläge des Auftrags und korrigiert teilbezahlte auf den bezahlten Betrag, in einem Schritt mit fortlaufenden Nummern; sind unbezahlte dabei, nur mit `acceptCancelOpenDownPayments`. `expectedSettlementRevision` bindet sie an die geprüften Abzüge (`409 FinalInvoicePaymentsChanged`). Gesperrt mit `409 DownPaymentDraftsOpen`, `409 DownPaymentPaymentUnknown`, `409 DownPaymentOverpaid`, `422 FinalInvoiceNegative`, `422 FinalInvoiceCashDiscount`. Hat sich der Auftrag geändert, seit eine Schlussrechnung oder Rechnung über den ganzen Auftrag angelegt wurde (ein Nachtrag beauftragt oder zurückgenommen, eine neue Auftragsbestätigung; `orderChanges`), lehnt es sie mit `409 ClosingInvoiceAddendaChanged` ab; dann legst du sie mit `replaceDraftId` und `replaceExpectedUpdatedAt` neu an. Einen Abschlag, dessen Betrag seitdem nicht neu berechnet wurde, lehnt es mit `409 DownPaymentOrderValueChanged` ab; speichern mit `downPayment` rechnet ihn neu. Keine bearbeitbaren Rechnungsfelder und kein Versand. Benötigt einen Schlüssel mit der Berechtigung `invoices:finalize`.
Angebot annehmen, ablehnen oder zurücksetzen POST
Hält fest, ob der Kunde ein ausgestelltes Angebot angenommen (`accepted`) oder abgelehnt (`rejected`) hat, wie in der App. `open` nimmt das Ergebnis zurück. Ein abgelaufenes Angebot lässt sich noch annehmen. bimetrics protokolliert jedes Ergebnis mit Schlüssel und Zeit; Angebot, PDF und Nummer bleiben unverändert. Das gleiche Ergebnis mit dem gleichen Grund ergibt `409 ProposalOutcomeUnchanged`, ein Entwurf `409 ProposalNotIssued`. Gibt es zum Angebot eine Auftragsbestätigung oder Rechnung, auch als Entwurf, sind Ablehnen und Zurücksetzen gesperrt (`409 ProposalConverted`, `context.draftId` und `context.kind` nennen den Beleg), ebenso bei einem ausgestellten Nachtrag zum Auftrag (`409 ProposalHasAddendum`). An einem Nachtrag heißt `accepted` beauftragt: Nach der ausgestellten Schlussrechnung oder Rechnung über den ganzen Auftrag geht das nicht mehr (`409 ProposalAddendumAcceptSettled`), und eine Beauftragung bleibt dann (`409 ProposalAddendumResetSettled`), ebenso, wenn seit der Beauftragung ein Abschlag zum Auftrag ausgestellt wurde (`409 ProposalAddendumBilled`). Kürzte der Nachtrag mit den beauftragten eine Zeile des Auftrags um mehr als ihre Menge, lässt er sich nicht beauftragen (`409 ProposalAddendumAcceptOverReduced`). deriveSalesDocument setzt ein Angebot von selbst auf angenommen. Idempotency-Key bei Wiederholung unverändert senden. Benötigt einen Schlüssel mit der Berechtigung `invoices:draft`.