bimetricsEntwickler
Belege

Belegdaten berichtigen

Als Markdown ansehen

Benötigte Berechtigung:documents:write(Nicht an DATEV exportierte Belege ändern)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
patch/api/document/{id}

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

Ändert nur angegebene Kopffelder, die Belegart, die Gegenpartei und Positionen. Fälligkeit und Ende des Leistungszeitraums lassen sich mit einem leeren String entfernen. Die Gegenpartei kommt aus einem Kontakt oder aus freien Angaben. Bei Positionen lassen sich Bezeichnung, Betrag, Kategorie, Steuersatz und Steuerfall ändern, Positionen hinzufügen oder entfernen, z. B. eine Position aufteilen. expectedVersion ist der fachliche Versionsdigest; sobald sich Beträge ändern, sichert expectedTotalMinor die neue Summe. Ausgestellte Rechnungen und Belege aus Dauerbuchungen sind geschützt. Festgeschriebene Buchungen werden storniert und neu gebucht, wie in der App auch nach einem DATEV-Export; dann nennt addendaMonths die Monate, die mit dem nächsten DATEV-Export des Monats als Nachtrag an die Kanzlei gehen; ein API-Schlüssel braucht dafür documents:correct, auch wenn nur die Abschreibung einer Anlage zum Beleg exportiert ist (assetAfa). Hat der Beleg eine erfasste Zahlung, wird sie bei einer neuen Gegenpartei mit auf deren Personenkonto umgebucht. Ist die Zahlungsbuchung festgeschrieben, ändert bimetrics sie nicht, sondern storniert sie zum Zahltag und bucht sie neu. Ist der Monat der Zahlung im Kassenbuch schon abgeschlossen, bucht bimetrics beides mit heutigem Datum in den laufenden Monat. Die Route antwortet mit 409 DocumentWriteLocked, dem Grund in context.detail und einem Code in context.reason, wenn die neue Gegenpartei mehr als das Personenkonto ändert, etwa die Umsatzsteuer, wenn der Beleg zusammen mit anderen Belegen einer Zahlung zugeordnet ist, wenn er erstattet oder mit einer Gutschrift verrechnet wurde oder wenn er in Fremdwährung bezahlt ist. Löst die normale Neubuchung und GoBD-Historie aus.

Benötigt einen Schlüssel mit der Berechtigung documents:write.

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

Gelesene Version und die geänderten Felder

application/json
  1. body

Korrektur eines Belegs. Für bereits exportierte Buchungen braucht dein Schlüssel zusätzlich documents:correct.

acceptRateDeviation?boolean

Nur true und nur mit euroTaxAmounts: bucht trotz einer Abweichung über 3 %, nachdem die Person sie bestätigt hat. bimetrics bucht die Steuer dann wie gesendet, auch wenn sie über der gesetzlichen liegt; abziehbar ist der Mehrbetrag nicht (§ 15 Abs. 1 UStG).

costCenterId?string

Kostenstelle oder Verteilung des Belegs als ID, ein leerer String entfernt sie. Ändert keinen Betrag und geht auch bei ausgestellten und bezahlten Belegen. Ist der Monat festgeschrieben, storniert bimetrics die Buchungen und bucht sie mit der neuen Kostenstelle neu; eine archivierte Kostenstelle wird abgelehnt. Hat der Beleg samt seiner Zuordnung keine Buchung auf einem Erfolgskonto, etwa der Beleg einer Gehaltsvorlage, ändert sich keine Buchung, und das geht auch nach dem DATEV-Export. Ein Beleg mit einer Anlage im Bestand, auch einem GWG, zählt nicht dazu: Die Abschreibung der Anlage übernimmt seine Kostenstelle und wird mit ihr neu gebucht, festgeschriebene per Storno zu ihrem Datum.

Muster^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})?$
counterparty?

Gegenpartei des Belegs, bei Ausgangsrechnungen der Empfänger, sonst der Aussteller: entweder contactId oder freie Angaben.

deliveryDate?

Neues Lieferdatum.

documentCurrency?string

Belegwährung korrigieren: ISO-4217-Code wie USD, EUR oder leer für Euro. Eine neue Währung hält die aktuelle Bruttosumme als originalTotalAmount fest; Beträge und Buchungen bleiben. Zurück auf Euro geht immer und leert auch originalTotalAmount und euroAmountSource. Eine andere Fremdwährung nur, solange euroAmountSource fehlt, sonst 409 DocumentCurrencyLocked.

dueDate?|

Neues Fälligkeitsdatum als Datumsobjekt oder als String YYYY-MM-DD. Ein leerer String entfernt es, null ändert nichts.

euroAmountsConfirmed?boolean

Nur true: Die Positionen dieses Belegs in Fremdwährung sind schon Euro (euroAmountSource person). Beendet „Euro-Betrag fehlt“, ändert keinen Betrag und keine Buchung. Bei einem Euro-Beleg 409 DocumentNotForeignCurrency.

euroAtMonthlyRate?boolean

Nur true: rechnet einen Beleg in Fremdwährung mit „Euro-Betrag fehlt“ zum Monatskurs des BMF um (§ 16 Abs. 6 UStG), jede Position zum Kurs des Monats, in dem ihre Leistung endet, höchstens zum Kurs des Rechnungsmonats. Die Positionen behalten foreignTotal, rateMonth und rate, euroAmountSource steht danach auf bmf. Vorher zeigt GET /api/document/{id}/monthly-rate, ob es geht. Geht auch mit zugeordneter Bankzahlung; den Rest zur Zahlung bucht man danach mit POST /api/match/{id}/exchange-difference als Kursdifferenz. 409 MonthlyRateUnavailable mit state und reason, solange der Kurs fehlt oder wenn die Zuordnung schon Skonto, Mahnkosten oder eine Kursdifferenz gebucht hat. Mit deutscher Umsatzsteuer auf einem Eingangsbeleg erst klären, ob er die Steuer in Euro ausweist; wenn ja, euroTaxAmounts statt euroAtMonthlyRate. Nicht zusammen mit euroTotalAmount oder euroAmountsConfirmed; expectedTotalMinor ist freiwillig.

euroTaxAmounts?array<>

Für einen Eingangsbeleg in Fremdwährung mit deutscher Umsatzsteuer und „Euro-Betrag fehlt“, der den Steuerbetrag in Euro ausweist: je Steuersatz seiner Positionen ein Eintrag mit vatPercentage (etwa 19) und amountMinor (Steuer in EUR-Cent laut Beleg). Daraus folgt der Kurs der Rechnung (Steuer in Fremdwährung ÷ Steuer in Euro); bimetrics rechnet jede Position damit um und legt die Rundung so, dass die gebuchte Vorsteuer je Satz auf den Cent dem ausgewiesenen Betrag entspricht (§ 15 Abs. 1 UStG). euroAmountSource steht danach auf person. Weicht der Kurs um mehr als 3 % vom Monatskurs ab (solange der fehlt, vom EZB-Kurs des Rechnungsdatums), 409 EuroTaxRateDeviation. 400 InvalidBookkeepingChange mit field euroTaxAmounts, wenn es kein Eingangsbeleg mit deutscher Umsatzsteuer einer Firma mit Vorsteuerabzug ist (askEuroTax in GET /api/document/{id}/monthly-rate), wenn nicht genau ein Betrag je Steuersatz über 0 % dabei ist oder wenn die Beträge nicht zu den Positionen ihres Satzes passen, etwa vertauscht. Bei einem Euro-Beleg 409 DocumentNotForeignCurrency. Nicht zusammen mit euroTotalAmount, euroAtMonthlyRate oder euroAmountsConfirmed; expectedTotalMinor ist freiwillig.

euroTotalAmount?integer

Euro-Betrag eines Belegs in Fremdwährung eintragen, wie „Euro-Betrag eintragen“ in der App: Bruttobetrag in EUR-Cent, größer 0. bimetrics rechnet die Positionen anteilig darauf um, Steuersätze und Kategorien bleiben, eine Gutschrift bleibt negativ; euroAmountSource steht danach auf person und „Euro-Betrag fehlt“ endet. Gilt als Betragsänderung, expectedTotalMinor ist dabei aber freiwillig und muss, wenn gesendet, die Summe danach sein. Bei einem Euro-Beleg 409 DocumentNotForeignCurrency.

expectedTotalMinor?integer

Bruttosumme aller Positionen nach der Änderung in EUR-Cent. Pflicht, sobald sich Beträge ändern (amountMinor, add oder remove), außer mit euroTotalAmount oder euroAtMonthlyRate (dann die Euro-Summe danach); bei Abweichung wird die Änderung abgelehnt.

expectedVersion?string

Zuletzt gelesener fachlicher Versionsdigest.

invoiceDate?

Neues Rechnungsdatum.

invoiceNumber?string

Neue Rechnungsnummer.

kind?string

Neue Belegart: invoice (Ausgangsrechnung) oder receipt (Eingangsbeleg). Bei offener Typprüfung werden die Kategorien eines unbearbeiteten, automatisch erkannten Belegs nach einem Richtungswechsel im Hintergrund neu vergeben. Ohne offene Typprüfung werden gegenläufige Kategorien geleert oder bei eindeutiger Erlöskategorie ersetzt. Fehlende Kategorien verhindern die Buchung. Geänderte Positionen werden gegen die neue Belegart geprüft. Als Gegenpartei zählt danach bei Ausgangsrechnungen der Empfänger, sonst der Aussteller.

Wert in"invoice""receipt"
performancePeriodFrom?

Beginn des Leistungszeitraums. Fehlt das Ende, ist es ein einzelnes Leistungsdatum.

performancePeriodTo?|

Ende des Leistungszeitraums als Datumsobjekt oder als String YYYY-MM-DD. Ein leerer String entfernt es, dann gilt der Beginn als einzelnes Leistungsdatum; null ändert nichts.

positions?array<>

Positionen ändern, hinzufügen oder entfernen, höchstens 100 Einträge. index bezieht sich auf die zuletzt gelesene Positionsliste; neue Positionen werden in Reihenfolge der Anfrage hinten angefügt. Die Liste wird nie als Ganzes ersetzt.

statedTotalAmount?integer

Gesamtbetrag laut Beleg in Hundertsteln, wie du ihn auf dem Original liest, negativ bei einer Gutschrift. 0 heißt, dass die Positionen keinen Gesamtbetrag ergeben müssen, wie „Summe passt so“ in der App: „Summe weicht ab“ endet, ohne dass sich eine Position ändert. Ändert keinen Betrag und keine Buchung und geht auch bei bezahlten Belegen.

Antworten

Erfolg.

application/json
  1. response

Korrigierter Beleg mit neuer Version.

addendaMonths?array<string>

Monate (JJJJ-MM), die schon an DATEV exportiert sind, in denen DATEV Buchungen des Belegs aber noch nicht hat, etwa Storno und Neubuchung dieser Berichtigung. Sie gehen erst mit dem nächsten DATEV-Export des Monats als Nachtrag an die Kanzlei. Dazu zählen Storno und Neubuchung eines automatischen GWG des Belegs, wenn der Export die Abschreibung an DATEV übergibt. Fehlt, wenn es keine gibt, und bei einer Wiederholung mit gleichem Idempotency-Key.

document?|

Aktueller Beleg nach Neubuchung.

kindChange?

Folgen eines ausgeführten Richtungswechsels.

replayed?boolean

True bei sicherer Wiederholung eines bereits erfolgreichen Aufrufs.

reversedFinalizedMonths?array<string>

Monate (YYYY-MM), in denen bimetrics festgeschriebene Buchungen storniert und mit geändertem Datum, Leistungszeitraum, Konto, Steuerkennzeichen oder Betrag neu gebucht hat. Ändert sich nur der Buchungstext oder die Zuordnung, fehlt der Monat. Hast du die Umsatzsteuer-Voranmeldung für einen dieser Monate oder, bei geändertem Datum, für den neuen Monat schon abgegeben, musst du sie womöglich berichtigen. Fehlt, wenn nichts storniert wurde, und bei einer Wiederholung mit demselben Idempotency-Key.

version?string

Neuer fachlicher Versionsdigest.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/document/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "document": {    "bookingErrors": null,    "bookings": [      {        "account": 4930,        "accountContra": 71007,        "accountingModel": "SKR03",        "amount": "43.89",        "bookingDate": {          "day": 27,          "month": 8,          "year": 2026        },        "bookingFlags": "v19%",        "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",        "createdAt": "2026-09-04T08:02:40Z",        "deletedAt": null,        "finalized": "2026-09-05T10:41:09Z",        "finalizedBy": "export",        "id": "f00b48c7-6eb3-4082-aba2-917944ac5f93",        "label": "Papierhaus Wendt KG, Kopierpapier A4 10 Pakete",        "performanceFrom": {          "day": 27,          "month": 8,          "year": 2026        },        "performanceTo": {          "day": 27,          "month": 8,          "year": 2026        },        "refBankTransactionId": null,        "refDocumentId": "a129ef0a-da5d-4204-804c-764d751bca95",        "refMatch": "d00419ed-ecab-4800-ad69-d482b73a6961",        "revertsAccountBookingId": null,        "updatedAt": "2026-09-05T10:41:09Z"      }    ],    "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",    "contentSource": "auto",    "createdAt": "2026-08-28T06:15:03Z",    "deletedAt": null,    "deliveryDate": null,    "documentContract": null,    "documentContractId": null,    "documentSeries": null,    "documentSeriesId": null,    "dueDate": {      "day": 10,      "month": 9,      "year": 2026    },    "id": "a129ef0a-da5d-4204-804c-764d751bca95",    "importOrigin": "email",    "invoiceDate": {      "day": 27,      "month": 8,      "year": 2026    },    "invoiceNumber": "2026-5531",    "invoicePositions": [      {        "additionalInfo": {          "freeOfVat": false,          "reverseCharge": false        },        "category": "office_supplies",        "label": "Kopierpapier A4 10 Pakete",        "subPositions": null,        "total": 4389,        "vatPercentage": "19"      }    ],    "issuer": {      "address": "Bahnhofstraße 8, 24103 Kiel",      "customerNumber": 1007,      "iban": "DE02500105170137075030",      "name": "Papierhaus Wendt KG",      "taxId": "DE246813579"    },    "kind": "receipt",    "match": {      "amountOpen": 0,      "autoMatch": false,      "bankTransactions": [        {          "bankTransactionId": "78c4ff15-f2a0-4eae-945d-73a969adab4b",          "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",          "createdAt": "2026-09-04T08:02:37Z",          "id": "b06c1337-d724-4854-bba8-d52bc6355c8b",          "matchId": "d00419ed-ecab-4800-ad69-d482b73a6961",          "updatedAt": "2026-09-04T08:02:37Z"        }      ],      "category": "payment",      "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",      "createdAt": "2026-09-04T08:02:37Z",      "documents": [        {          "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",          "createdAt": "2026-09-04T08:02:37Z",          "documentId": "a129ef0a-da5d-4204-804c-764d751bca95",          "id": "e1331e65-c539-4c84-9271-66cc20f52910",          "matchId": "d00419ed-ecab-4800-ad69-d482b73a6961",          "updatedAt": "2026-09-04T08:02:37Z"        }      ],      "id": "d00419ed-ecab-4800-ad69-d482b73a6961",      "matchingRule": {        "active": true,        "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",        "createdAt": "2026-09-04T08:02:41Z",        "id": "5e0f6a4b-8d2c-4f7e-9b1a-3c6d2e8f4a71",        "updatedAt": "2026-09-04T08:02:41Z"      },      "matchingRuleId": "5e0f6a4b-8d2c-4f7e-9b1a-3c6d2e8f4a71",      "updatedAt": "2026-09-04T08:02:37Z"    },    "paymentTerms": "Der Betrag wird per SEPA-Lastschrift eingezogen.",    "performancePeriodFrom": null,    "performancePeriodTo": null,    "recipient": {      "address": "Mühlenkamp 31, 22303 Hamburg",      "customerNumber": null,      "iban": "",      "name": "Hansen & Kowalski Werbetechnik GmbH",      "taxId": "DE123456789"    },    "source": "",    "updatedAt": "2026-09-05T10:41:09Z",    "uploadDocument": {      "blob": {        "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",        "createdAt": "2026-08-28T06:15:03Z",        "id": "138b7a6f-7e79-4040-bc64-3638e95d9682",        "length": 48213,        "mime": "application/pdf",        "originalFilename": "Rechnung_2026-5531.pdf",        "sha256": "a5a23fdf5e666babc92d877ccf80202609c25ae54b48095f0eaa02289012ca54",        "updatedAt": "2026-08-28T06:15:03Z"      },      "blobId": "138b7a6f-7e79-4040-bc64-3638e95d9682",      "creatorUserCompanyId": "53cd10a9-c864-4dc3-a777-9860d59efe6c",      "einvoiceValidation": {        "checkedAt": "2026-08-28T06:15:19Z",        "engine": "mustang-2.26.0",        "errorCount": 0,        "status": "warnings",        "warningCount": 1      },      "ocrFinishedAt": "2026-08-28T06:15:19Z",      "ocrStartedAt": "2026-08-28T06:15:04Z",      "ocrStatus": "success",      "pageCount": 0,      "pagesRead": 0,      "readFromEinvoice": true    },    "uploadDocumentId": "08f65ded-eef9-4cdf-8954-ace8add6eb53",    "version": ""  },  "replayed": false,  "version": "0e8ca8e3db88d8d5b74c965d0e17598a5909240c88376e0b0a4a23e53ee9356f"}