Beleg lesen
Benötigte Berechtigung:read(Daten lesen)
Liefert einen Beleg mit erkannten Daten, Positionen, Zuordnung (match) und Buchungen. Für einen gelöschten Beleg antwortet die Route mit 404, auch wenn bimetrics ihn beim Löschen behalten hat, etwa wegen festgeschriebener Buchungen.
Benötigt einen Schlüssel mit der Berechtigung read.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
id*stringID des Belegs (UUID).
uuidErfolg.
application/json- response
Ein Beleg: Ausgangsrechnung oder Eingangsbeleg mit den erkannten bzw. erfassten Daten.
bookingErrors?array<>|Buchungsfehler, Warnungen und Hinweise. Bei einem Fehler (level 30) bucht bimetrics den Beleg gar nicht oder nicht verlässlich, bis er behoben ist. Es zählen nur Einträge des Kontenrahmens, mit dem die Firma heute bucht (accountingModel).
bookings?array<>|Buchungen des Belegs.
cashDiscount?Skonto einer in bimetrics erstellten Ausgangsrechnung; fehlt ohne Skonto.
companyId?stringID der Firma.
uuidcontentSource?stringHerkunft der Belegdaten: auto erkannt, manual erfasst, collection aus Dauerbuchung oder Buchungsvorlage.
costCenterId?stringKostenstelle oder Verteilung als ID; fehlt ohne.
uuidcreatedAt?stringAnlage in bimetrics.
date-timedeletedAt?|Gilt als gelöscht seit diesem Zeitpunkt; null, solange nicht gelöscht. Auch ein Beleg, den bimetrics beim Löschen behält, etwa wegen festgeschriebener Buchungen, gilt ab dann als gelöscht. Gelöschte Belege liefert nur filterDocuments mit includeDeleted.
date-timedeliveryDate?|Liefer- bzw. Leistungsdatum.
documentContract?|Die Dauerbuchung, aus der der Beleg entstand; sonst null.
documentContractId?|ID der Dauerbuchung, aus der der Beleg entstand; sonst null.
uuiddocumentCurrency?stringBelegwährung nach ISO 4217, wenn der Beleg nicht in Euro ist, z. B. USD; fehlt bei Euro. Gebucht wird mit den Beträgen der Positionen als Euro. Solange euroAmountSource fehlt, ist das der Betrag vom Beleg, und die App zeigt „Euro-Betrag fehlt“. Korrigieren mit documentCurrency in PATCH /api/document/{id}.
documentSeries?|Die Buchungsvorlage, aus der der Beleg entstand; sonst null.
documentSeriesId?|ID der Buchungsvorlage, aus der der Beleg entstand; sonst null.
uuiddueDate?|Fälligkeitsdatum.
euroAmountSource?stringWoher der Euro-Betrag eines Belegs in Fremdwährung stammt: payment aus der zugeordneten Bankzahlung übernommen, person von einer Person eingetragen oder bestätigt (euroTotalAmount oder euroAmountsConfirmed in PATCH /api/document/{id}). Fehlt, solange der Euro-Betrag fehlt.
"payment""person"id?stringID des Belegs.
uuidimportOrigin?|Eingangsweg: upload, email, generated (in bimetrics erstellt) oder collection (aus Dauerbuchung oder Buchungsvorlage).
invoiceCorrections?array<>Quellgebundene Rechnungskorrekturen des Originalbelegs.
invoiceDate?|Rechnungsdatum.
invoiceNumber?stringRechnungsnummer.
invoicePositions?array<>|Positionen; null, solange nichts erkannt ist.
invoiceRole?stringRolle einer ausgestellten Rechnung im Auftrag: down_payment (Abschlag) oder final (Schlussrechnung); fehlt bei allen anderen Belegen.
"down_payment""final"issuedInvoice?Vom Server ermittelter Ausstellungsstatus; fehlt bei gewöhnlichen importierten Belegen. Ausgestellte Rechnungen und Stornorechnungen können nicht verändert oder gelöscht werden.
issuer?Aussteller.
kind?stringBelegart: invoice Ausgangsrechnung, receipt Eingangsbeleg.
"invoice""receipt"kindReview?boolean„Belegtyp prüfen“: Die Erkennung konnte nicht sicher entscheiden, ob Ausgangsrechnung oder Eingangsbeleg; kind ist nur die Vermutung. Bis jemand den Belegtyp wählt (kind in PATCH /api/document/{id}, auch mit demselben Wert, oder POST /api/document/bulk/kind), wird der Beleg nicht gebucht, nicht exportiert und nicht zugeordnet. Fehlt sonst.
match?|Zuordnung zu Umsätzen und anderen Belegen; null ohne Zuordnung.
originalTotalAmount?integerBruttosumme in der Belegwährung in Hundertsteln, auch bei Währungen ohne Nachkommastellen. Festgehalten, als die Währung erkannt oder gesetzt wurde. Fehlt bei Euro.
paymentTerms?stringZahlungsbedingungen als Text.
performancePeriodFrom?|Beginn des Leistungszeitraums.
performancePeriodTo?|Ende des Leistungszeitraums.
possibleDuplicateOfId?string„Möglicher Doppelbeleg“: ID eines älteren Belegs derselben Firma, der wahrscheinlich dasselbe Papier ist, nur ein zweites Mal hochgeladen (anderer Scan, andere Datei). Belegart, Geschäftspartner und Vorzeichen des Bruttobetrags sind gleich, dazu entweder die Rechnungsnummer (Leerzeichen und Groß-/Kleinschreibung egal) bei höchstens 1 Cent Unterschied im Bruttobetrag, solange sich die Rechnungsdaten nicht widersprechen, oder das Rechnungsdatum bei höchstens 1 % Unterschied oder einer fast gleich großen Datei mit gleicher Seitenzahl ab zwei Seiten, solange sich die Rechnungsnummern nicht widersprechen. Passen mehrere, ist es der ähnlichste. Nur ein Hinweis: bimetrics sperrt und löscht nichts. Ist es ein Doppelbeleg, löschst du einen der beiden mit DELETE /api/document/{id}. Fehlt sonst, auch bei stornierten, ausgestellten und festgeschriebenen Belegen.
uuidrecipient?Empfänger.
recordedPayments?array<>Dokumentierte Bar- und Verrechnungszahlungen; keine Bankumsätze.
remainingPaymentMinor?integerNach Zuordnungen und dokumentierten Zahlungen verbleibender Betrag in Cent.
reversesCorrectionDocumentId?stringAusgestellte Korrektur, die dieser Gegenbeleg vollständig aufhebt.
uuidsource?stringAuslösender Zugang: web, api oder mcp.
sourceInvoiceDocumentId?stringUnveränderter Originalbeleg, auf den sich eine Rechnungskorrektur bezieht.
uuidstatedTotalAmount?integerGesamtbetrag brutto, wie die Erkennung ihn auf dem Beleg gelesen hat, in Hundertsteln wie die Positionen (bei Fremdwährung in der Belegwährung). Weicht die Summe der Positionen um mehr als einen Cent je Position davon ab, zeigt die App „Die Summe der Positionen weicht vom Gesamtbetrag im Beleg ab.“, der Beleg steht unter „Zu prüfen“, und Meldungen.csv im DATEV-Export nennt beide Beträge. Gebucht wird mit den Positionen. Korrigieren oder mit 0 beenden („Summe passt so“) mit statedTotalAmount in PATCH /api/document/{id}. Nach der Übernahme eines Euro-Betrags (euroAmountSource) wird nicht mehr verglichen. Fehlt, wenn kein Gesamtbetrag gelesen wurde oder er nicht im Text des Belegs steht.
updatedAt?stringLetzte Änderung, auch einer Zuordnung: Zuordnen, Aufheben und ein neuer offener Betrag (match.amountOpen) ändern den Wert.
date-timeuploadDocument?|Die hochgeladene Datei und der Stand ihrer Erkennung.
uploadDocumentId?|ID der hochgeladenen Datei; null bei Belegen aus Dauerbuchungen oder Buchungsvorlagen.
uuidversion?stringFachlicher Versionsdigest. Unverändert als expectedVersion bei Belegkorrektur oder Zahlung übergeben.
curl --fail-with-body "https://app.bimetrics.de/api/document/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Authorization: Bearer $BIMETRICS_API_KEY"{ "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": ""}Belege suchen POST
Sucht Belege der Firma mit einem Filter und liefert eine Seite der Treffer (`items`) mit der Gesamtzahl (`total`). Ohne Filter (`{}`) liefert die Route alle Belege, die nicht gelöscht sind, höchstens 1000 je Seite. Gelöschte Belege, auch solche, die bimetrics beim Löschen behält, etwa wegen festgeschriebener Buchungen, kommen nur mit `includeDeleted`. Benötigt einen Schlüssel mit der Berechtigung `read`.
Belegdaten berichtigen PATCH
Ä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, Belege aus Dauerbuchungen und Belege mit an DATEV exportierten Buchungen sind geschützt; andere festgeschriebene Buchungen werden storniert und neu gebucht. Löst die normale Neubuchung und GoBD-Historie aus. Benötigt einen Schlüssel mit der Berechtigung `documents:write`.