bimetricsEntwickler
Ausgangsrechnungen

Rechnung, Korrektur, Angebot oder Auftragsbestätigung ausstellen

Als Markdown ansehen

Benötigte Berechtigung:invoices:finalize(Ausgangsrechnungen erstellen und stornieren)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
put/api/draft/{id}/finalize

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

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.

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 Objekts 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

Request-Body

application/json
  1. body

Gespeicherten Entwurf mit Versionsbedingungen ausstellen, ohne Rechnungsinhalt zu ändern.

acceptCancelOpenDownPayments?boolean

Nur Schlussrechnung: Zustimmung, dass das Ausstellen die unbezahlten Abschläge des Auftrags storniert oder auf 0 € korrigiert (settlement.cancelled, settlement.corrected und settlement.acceptRequired aus checkDraft). Ohne sie und mit solchen Abschlägen 422 OpenDownPaymentsNotAccepted.

expectedCapacityRevision?string

Optional ausschließlich für Rechnungskorrekturen und deren Gegenbelege: unveränderte revision aus getCorrectionCapacity. Bindet die Ausgabe zusätzlich an die geprüfte Restkapazität; ein geänderter Stand liefert 409 VersionConflict und erfordert erneute Prüfung. Bei anderen Belegarten weglassen.

expectedSettlementRevision?string

Nur Schlussrechnung, optional: settlement.revision aus checkDraft. Bindet das Ausstellen an die geprüften Abzüge; hat sich seither ein Zahlstand geändert, kommt 409 FinalInvoicePaymentsChanged, dann neu prüfen.

expectedUpdatedAt?|

Exakter zuletzt gelesener updatedAt-Wert einschließlich Sekundenbruchteilen.

Formatdate-time

Antworten

Erfolg.

application/json
  1. response

Ergebnis einer Rechnung, Rechnungskorrektur, deren Gegenbeleg, eines Angebots, einer Auftragsbestätigung oder eines Vollstornos.

document?

Ausgestellter Rechnungs-, Korrektur-, Gegen- oder Stornobeleg.

orderConfirmation?

Ausgestellte Auftragsbestätigung ohne Buchung oder XML.

quotaNotice?

Nur bei einer Rechnung, nach der das Dokumentkontingent ausgeschöpft ist; die Rechnung ist trotzdem ausgestellt.

salesProposal?

Ausgestelltes Angebot ohne Buchung oder XML.

warnings?array<>

Hinweise, die das Ausstellen nicht verhindert haben: IssueDateBeforeLastInvoice, wenn das Rechnungsdatum vor deiner letzten Rechnung liegt. Das ist erlaubt, fällt aber bei einer Betriebsprüfung auf. Fehlt ohne Hinweis und bei einer Wiederholung mit demselben Idempotency-Key.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/draft/497f6eca-6276-4993-bfeb-53cbbbba6f08/finalize" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "document": {    "bookingErrors": null,    "bookings": [      {        "account": 8400,        "accountContra": 11004,        "accountingModel": "SKR03",        "amount": "-1785",        "bookingDate": {          "day": 1,          "month": 9,          "year": 2026        },        "bookingFlags": "ust19%",        "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",        "createdAt": "2026-09-12T07:30:19Z",        "deletedAt": null,        "finalized": null,        "id": "743f74e5-29fb-46ba-b919-21e48af483be",        "label": "Brauhaus Elbwiese GmbH, Fassadenbeschriftung Entwurf und Montage",        "performanceFrom": {          "day": 1,          "month": 9,          "year": 2026        },        "performanceTo": {          "day": 1,          "month": 9,          "year": 2026        },        "refBankTransactionId": null,        "refDocumentId": "3026096b-614f-40d3-8749-8acf9b529480",        "refMatch": "e21b3d18-17ea-4318-810c-919ec0a94dcb",        "revertsAccountBookingId": null,        "updatedAt": "2026-09-12T07:30:19Z"      }    ],    "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",    "contentSource": "auto",    "createdAt": "2026-09-01T09:12:44Z",    "deletedAt": null,    "deliveryDate": null,    "documentContract": null,    "documentContractId": null,    "documentSeries": null,    "documentSeriesId": null,    "dueDate": {      "day": 15,      "month": 9,      "year": 2026    },    "id": "3026096b-614f-40d3-8749-8acf9b529480",    "importOrigin": "upload",    "invoiceDate": {      "day": 1,      "month": 9,      "year": 2026    },    "invoiceNumber": "RE-2026-0142",    "invoicePositions": [      {        "additionalInfo": {          "freeOfVat": false,          "reverseCharge": false        },        "category": "sales_income",        "label": "Fassadenbeschriftung Entwurf und Montage",        "subPositions": null,        "total": 178500,        "vatPercentage": "19"      }    ],    "issuer": {      "address": "Mühlenkamp 31, 22303 Hamburg",      "customerNumber": null,      "iban": "DE89370400440532013000",      "name": "Hansen & Kowalski Werbetechnik GmbH",      "taxId": "DE123456789"    },    "kind": "invoice",    "match": {      "amountOpen": 0,      "autoMatch": true,      "bankTransactions": [        {          "bankTransactionId": "a1ba4b85-5bd8-4cef-bbbd-16eaa2c46033",          "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",          "createdAt": "2026-09-12T07:30:15Z",          "id": "840529df-2d2a-42ea-afa3-3704d855634f",          "matchId": "e21b3d18-17ea-4318-810c-919ec0a94dcb",          "updatedAt": "2026-09-12T07:30:15Z"        }      ],      "category": "payment",      "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",      "createdAt": "2026-09-12T07:30:15Z",      "documents": [        {          "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",          "createdAt": "2026-09-12T07:30:15Z",          "documentId": "3026096b-614f-40d3-8749-8acf9b529480",          "id": "3432135f-5b01-4288-9764-e1ff7d061777",          "matchId": "e21b3d18-17ea-4318-810c-919ec0a94dcb",          "updatedAt": "2026-09-12T07:30:15Z"        }      ],      "id": "e21b3d18-17ea-4318-810c-919ec0a94dcb",      "matchingRule": null,      "matchingRuleId": null,      "updatedAt": "2026-09-12T07:30:15Z"    },    "paymentTerms": "Zahlbar innerhalb von 14 Tagen ohne Abzug.",    "performancePeriodFrom": null,    "performancePeriodTo": null,    "recipient": {      "address": "Am Sandtorkai 12, 20457 Hamburg",      "customerNumber": 1004,      "iban": "DE02120300000000202051",      "name": "Brauhaus Elbwiese GmbH",      "taxId": "DE987654321"    },    "source": "",    "updatedAt": "2026-09-12T07:30:19Z",    "uploadDocument": {      "blob": {        "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",        "createdAt": "2026-09-01T09:12:44Z",        "id": "cd47afe0-7d1b-4c2a-8f7b-cbd58d92a54a",        "length": 84213,        "mime": "application/pdf",        "originalFilename": "RE-2026-0142.pdf",        "sha256": "1ca20000989555ec85b52711c84520f26bac2604307222e5cd978605783f6bc2",        "updatedAt": "2026-09-01T09:12:44Z"      },      "blobId": "cd47afe0-7d1b-4c2a-8f7b-cbd58d92a54a",      "creatorUserCompanyId": "53cd10a9-c864-4dc3-a777-9860d59efe6c",      "ocrFinishedAt": "2026-09-01T09:13:02Z",      "ocrStartedAt": "2026-09-01T09:12:45Z",      "ocrStatus": "success",      "pageCount": 2,      "pagesRead": 2    },    "uploadDocumentId": "e0ba087b-4b49-4137-8bb8-555a24619eae",    "version": ""  }}

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

Nachtrag zu einem Auftrag anlegen POST

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