bimetricsEntwickler
Belege

Prüfbericht einer E-Rechnung lesen

Als Markdown ansehen

Benötigte Berechtigung:read(Daten lesen)

GET
/api/document/{id}/einvoice-validation-report

Liefert das Ergebnis der Prüfung einer eingehenden E-Rechnung mit den Meldungen ihres Prüfberichts: Stufe, Regel, Text und Fundstelle. bimetrics prüft dabei nicht neu, die Meldungen stammen aus dem Bericht, der beim Empfang entstand. Texte und Fundstellen können Rechnungsdaten zitieren. Hat der Beleg keine Prüfung, antwortet die Route mit 404, etwa bei einem Scan oder einer E-Rechnung, die vor dem 27.09.2026 einging. Bei unchecked gibt es keinen Bericht: Die Meldungen fehlen, und format=xml antwortet mit 404.

Benötigt einen Schlüssel mit der Berechtigung read.

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 Belegs (UUID).

Formatuuid

Query-Parameter

format?"xml"

xml liefert statt der Meldungen den Prüfbericht als Datei pruefbericht.xml, so wie das Prüfprogramm ihn schrieb.

Wert in"xml"

Antworten

Erfolg. Mit format=xml die Datei pruefbericht.xml.

  1. response

Prüfung einer eingehenden E-Rechnung mit den Meldungen des gespeicherten Prüfberichts.

checkedAt?string

Zeitpunkt der Prüfung.

Formatdate-time
engine?string

Prüfprogramm mit Version, etwa mustang-2.26.0; nur mustang, wenn es nicht lief.

errorCount?integer

Anzahl der Fehler im Prüfbericht.

messages?array<>

Meldungen des Prüfberichts, Fehler zuerst, dann Warnungen und Anmerkungen, je in der Reihenfolge des Berichts; höchstens 500. Fehlt bei unchecked.

status?string

Stufe: valid (gültig), warnings (gültig mit Hinweisen), invalid (ungültig) oder unchecked (nicht geprüft, das Prüfprogramm lief nicht).

Wert in"valid""warnings""invalid""unchecked"
warningCount?integer

Anzahl der Hinweise (Warnungen) im Prüfbericht.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/document/497f6eca-6276-4993-bfeb-53cbbbba6f08/einvoice-validation-report" \  -H "Authorization: Bearer $BIMETRICS_API_KEY"
Beispielantwort
{  "checkedAt": "2026-11-18T08:41:12Z",  "engine": "mustang-2.26.0",  "errorCount": 1,  "messages": [    {      "level": "error",      "location": "/CrossIndustryInvoice[1]/SupplyChainTradeTransaction[1]/ApplicableHeaderTradeAgreement[1]",      "ruleId": "BR-DE-15",      "text": "Das Element \"Buyer reference\" (BT-10) muss übermittelt werden."    },    {      "level": "warning",      "location": "/CrossIndustryInvoice[1]/SupplyChainTradeTransaction[1]/IncludedSupplyChainTradeLineItem[1]/SpecifiedTradeProduct[1]/BuyerAssignedID[1]",      "ruleId": "PEPPOL-EN16931-R008",      "text": "Document MUST not contain empty elements. (still status warning)"    }  ],  "status": "invalid",  "warningCount": 1}

Löschen eines Belegs prüfen GET

Sagt, was `DELETE /api/document/{id}` gerade tun würde, und ändert nichts: `outcome` `deleted` (Beleg, Datei und offene Buchungen verschwinden aus bimetrics, es gibt keinen Papierkorb), `cancelled` (festgeschriebene Buchungen bleiben und werden in ihren Monaten storniert, `reversedFinalizedMonths`, der Beleg bleibt als storniert stehen) oder `retained_copy` (eine hochgeladene Kopie derselben Datei übernimmt, Beleg, Buchungen und Zuordnung bleiben). Geht es nicht, nennt `refusedBecause` den Grund. Sende `version`, `outcome` und `currentRepresentativeId` beim Löschen unverändert mit. Benötigt einen Schlüssel mit der Berechtigung `read`.

Umrechnung zum Monatskurs prüfen GET

Sagt für einen Beleg in Fremdwährung mit „Euro-Betrag fehlt“, ob `euroAtMonthlyRate` in `PATCH /api/document/{id}` ihn jetzt zum Monatskurs des BMF umrechnen kann, und ändert nichts. `ready` nennt die Kurse je Monat und die Euro-Summe danach. `waiting` heißt, der Kurs gilt ab `availableFrom`: Das BMF gibt ihn am ersten Arbeitstag des Folgemonats bekannt. `late`: Der Kurs ist überfällig. `noRate`: Für die Währung gibt es keinen Monatskurs, dann den Euro-Betrag mit `euroTotalAmount` eintragen. `notEligible` mit `reason`, etwa `settledPayment` (die Zuordnung hat schon Skonto, Mahnkosten oder eine Kursdifferenz gebucht). Ist eine Bankzahlung ohne solchen Ausgleich zugeordnet, rechnet `euroAtMonthlyRate` trotzdem um; den Rest zur Zahlung bucht danach `POST /api/match/{id}/exchange-difference` als Kursdifferenz. `askEuroTax`: Bei deutscher Umsatzsteuer auf einem Eingangsbeleg erst fragen, ob er die Steuer in Euro ausweist; wenn ja, `euroTaxAmounts` statt `euroAtMonthlyRate`. `exported` heißt, die Buchungen sind schon an DATEV gegangen; beim Umrechnen storniert bimetrics dann wie in der App und bucht neu, als Nachtrag (`addendaMonths`; ein API-Schlüssel braucht dafür `documents:correct`). Benötigt einen Schlüssel mit der Berechtigung `read`.