bimetricsEntwickler
Ausgangsrechnungen

Neue Version eines Angebots anlegen

Als Markdown ansehen

Benötigte Berechtigung:invoices:draft(Rechnungsentwürfe verwalten)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/draft/{id}/proposal-version

Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.

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.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.

Pfadparameter

id*string

ID des ausgestellten Angebots in dieser Firma (UUID).

Formatuuid

Header-Parameter

Idempotency-Key*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.

Muster^[!-~]+$
Länge1 <= length <= 128

Antworten

Erfolg.

application/json
  1. 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?string

ID der Firma.

Formatuuid
createdAt?string

Anlage in bimetrics.

Formatdate-time
creatorUserCompanyId?string

ID der erstellenden Mitgliedschaft.

Formatuuid
deductedBy?

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.

Formatdate-time
documentId?|

ID des ausgestellten Rechnungsbelegs; null bei offenem Entwurf.

Formatuuid
documentMail?

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?

Gespeicherter Rechnungsinhalt.

externalRef?string

Externe Bestellreferenz.

finalTotal?integer

Bruttosumme des ausgestellten Belegs in Cent.

id?string

ID des Entwurfs.

Formatuuid
invoiceCorrection?

Quellgebundener Grund und Bruttokorrekturbeträge je Position.

invoiceNumber?string

Arbeitsnummer; nach Abschluss endgültige Rechnungsnummer.

invoiceRole?string

Rolle der Rechnung im Auftrag: down_payment (Abschlag) oder final (Schlussrechnung), fest ab dem Ableiten; fehlt bei allen anderen Entwürfen. Filterbar in filterDrafts.

Wert in"down_payment""final"
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?|

Ausgestellte Auftragsbestätigung; null bei offenem Entwurf.

Formatuuid
originalInvoiceId?|

Originalentwurf für eine Stornorechnung; sonst null.

Formatuuid
originalTotal?integer

Bruttosumme 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?string

Ausgestellte Korrektur, die dieser Gegenbeleg aufhebt.

Formatuuid
salesProposalId?|

ID eines erstellten Angebots, falls vorhanden.

Formatuuid
settledByFinalDraftId?string

Nur Storno oder Korrektur eines Abschlags: die Schlussrechnung, deren Ausstellen diesen Beleg erzeugt hat.

Formatuuid
source?string

Zugang bei Anlage: web, api, mcp oder series für erzeugte Serienrechnungen.

sourceInvoiceDocumentId?string

Unverändertes Original einer Rechnungskorrektur.

Formatuuid
sourceOrderConfirmationId?|

Ausdrücklich gewählte finale AB als Rechnungsquelle; sonst null.

Formatuuid
sourceSalesProposalId?|

Ursprüngliches Angebot, falls vorhanden.

Formatuuid
taxCase?

Beim Abschluss eingefrorener Steuerfall.

typeCode?string

EN-16931-Dokumenttyp: Rechnung 380, Rechnungskorrektur 381, Vollstorno oder Korrektur-Gegenbeleg 384.

updatedAt?string

Letzte Änderung.

Formatdate-time
Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/draft/497f6eca-6276-4993-bfeb-53cbbbba6f08/proposal-version" -X POST \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001"
Beispielantwort
{  "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-0045",  "kind": "proposal",  "orderConfirmationId": null,  "originalInvoiceId": null,  "proposalVersion": {    "baseNumber": "AN-2026-0042",    "number": "AN-2026-0042-2",    "predecessorId": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b",    "version": 2  },  "salesProposalId": null,  "source": "api",  "sourceOrderConfirmationId": null,  "sourceSalesProposalId": null,  "typeCode": "",  "updatedAt": "2026-09-01T08:01:02.123456Z"}

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

Gespeicherten Rechnungsentwurf prüfen POST

Prüft den gespeicherten Entwurf und liefert Steuerfall, Problemcodes und vorgesehene Konten. Meldet auch einen Entwurf ohne Position (`ItemsRequired`), einen fehlenden Firmennamen (`company_name_required`), unvollständige Anschriften von Firma oder Kunde (`InvoiceAddressRequired`) sowie eine unbestätigte Versteuerung (`SellerTaxStatusUnconfirmed`) oder fehlende Steuernummer der Firma (`SellerTaxIdRequired`) als blockierend, weil das Abschließen sie ablehnt. Liegt das Rechnungsdatum vor deiner letzten Rechnung, weist `IssueDateBeforeLastInvoice` darauf hin, ohne zu blockieren. Hat ein Steuerfall ohne Umsatzsteuer auf der Rechnung eine Position mit Bruttopreis auf 0 % gesetzt, weist `gross_price_without_vat` darauf hin, ebenfalls ohne zu blockieren. Der Hinweis nennt den Einzelpreis, den der Kunde zahlt, und den Einzelpreis, aus dem die frühere Umsatzsteuer herausgerechnet ist. Je Position nennt `lines[].allowedRates` die Steuersätze, die ihr Steuerfall erlaubt. Bei einer Schlussrechnung nennt `settlement` Abzüge, Stornos, Korrekturen und den Revisionswert, bei Abschlag und Schlussrechnung `billing` den Stand des Auftrags. Legt keine Kontakte, Rechnungen oder Buchungen an. Kein Anfrageinhalt erforderlich. Benötigt einen Schlüssel mit der Berechtigung `invoices:draft`.