bimetricsEntwickler
Belege

Beleg lesen

Als Markdown ansehen

Benötigte Berechtigung:read(Daten lesen)

GET
/api/document/{id}

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.

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

Antworten

Erfolg.

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

ID der Firma.

Formatuuid
contentSource?string

Herkunft der Belegdaten: auto erkannt, manual erfasst, collection aus Dauerbuchung oder Buchungsvorlage.

costCenterId?string

Kostenstelle oder Verteilung als ID; fehlt ohne.

Formatuuid
createdAt?string

Anlage in bimetrics.

Formatdate-time
deletedAt?|

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.

Formatdate-time
deliveryDate?|

Liefer- bzw. Leistungsdatum.

documentContract?|

Die Dauerbuchung, aus der der Beleg entstand; sonst null.

documentContractId?|

ID der Dauerbuchung, aus der der Beleg entstand; sonst null.

Formatuuid
documentCurrency?string

Belegwä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.

Formatuuid
dueDate?|

Fälligkeitsdatum.

euroAmountSource?string

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

Wert in"payment""person"
id?string

ID des Belegs.

Formatuuid
importOrigin?|

Eingangsweg: upload, email, generated (in bimetrics erstellt) oder collection (aus Dauerbuchung oder Buchungsvorlage).

invoiceCorrections?array<>

Quellgebundene Rechnungskorrekturen des Originalbelegs.

invoiceDate?|

Rechnungsdatum.

invoiceNumber?string

Rechnungsnummer.

invoicePositions?array<>|

Positionen; null, solange nichts erkannt ist.

invoiceRole?string

Rolle einer ausgestellten Rechnung im Auftrag: down_payment (Abschlag) oder final (Schlussrechnung); fehlt bei allen anderen Belegen.

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

Belegart: invoice Ausgangsrechnung, receipt Eingangsbeleg.

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

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

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

Formatuuid
recipient?

Empfänger.

recordedPayments?array<>

Dokumentierte Bar- und Verrechnungszahlungen; keine Bankumsätze.

remainingPaymentMinor?integer

Nach Zuordnungen und dokumentierten Zahlungen verbleibender Betrag in Cent.

reversesCorrectionDocumentId?string

Ausgestellte Korrektur, die dieser Gegenbeleg vollständig aufhebt.

Formatuuid
source?string

Auslösender Zugang: web, api oder mcp.

sourceInvoiceDocumentId?string

Unveränderter Originalbeleg, auf den sich eine Rechnungskorrektur bezieht.

Formatuuid
statedTotalAmount?integer

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

Letzte Änderung, auch einer Zuordnung: Zuordnen, Aufheben und ein neuer offener Betrag (match.amountOpen) ändern den Wert.

Formatdate-time
uploadDocument?|

Die hochgeladene Datei und der Stand ihrer Erkennung.

uploadDocumentId?|

ID der hochgeladenen Datei; null bei Belegen aus Dauerbuchungen oder Buchungsvorlagen.

Formatuuid
version?string

Fachlicher Versionsdigest. Unverändert als expectedVersion bei Belegkorrektur oder Zahlung übergeben.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/document/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Authorization: Bearer $BIMETRICS_API_KEY"
Beispielantwort
{  "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": ""}