Beleg erneut lesen
Benötigte Berechtigung:upload(Belege hochladen)
Echte Wirkung
/api/document/{id}/reading/retryKein Testversand aus der Dokumentation: Jeder Aufruf legt einen echten Beleg an. Nutze das Codebeispiel mit einer Datei, die wirklich in die Firma gehört.
Startet die Erkennung eines Belegs neu, dessen Lesen fehlgeschlagen ist (ocrStatus failed), wie „Erneut lesen“ in der App. Der Beleg wartet danach sofort wieder (ocrStatus pending), die Antwort ist der Beleg in diesem Stand. Die Datei bleibt dieselbe, du lädst nichts neu hoch. Das erneute Lesen zählt im Tarif als weiterer Beleg ins Kontingent. Ist der Beleg schon gelesen, wartet er oder wird er gerade gelesen, antwortet die Route mit 409 DocumentReadingNotFailed, auch beim zweiten Aufruf. Einen von Hand erfassten Beleg lehnt sie mit 409 DocumentReadingManual ab, einen mit festgeschriebenen Buchungen mit 409 DocumentReadingFinalized und eine in bimetrics ausgestellte Rechnung mit 409 DocumentReadingIssued. Idempotency-Key bei Wiederholung unverändert senden.
Benötigt einen Schlüssel mit der Berechtigung upload.
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).
uuidIdempotency-Key*stringStabiler 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.
^[!-~]+$1 <= length <= 128Erfolg.
application/json- response
Ein Beleg: Ausgangsrechnung oder Eingangsbeleg mit den erkannten bzw. erfassten Daten.
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.
uuidupdatedAt?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/reading/retry" -X POST \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001"{ "bookings": null, "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "contentSource": "auto", "createdAt": "2026-09-26T14:03:27Z", "deletedAt": null, "deliveryDate": null, "documentContract": null, "documentContractId": null, "documentSeries": null, "documentSeriesId": null, "dueDate": null, "id": "a2543540-c7ca-413d-8bcc-1ef3427e8aa4", "importOrigin": "upload", "invoiceDate": null, "invoiceNumber": "", "invoicePositions": null, "issuer": { "address": "", "customerNumber": null, "iban": "", "name": "", "taxId": "" }, "kind": "receipt", "match": null, "paymentTerms": "", "performancePeriodFrom": null, "performancePeriodTo": null, "recipient": { "address": "", "customerNumber": null, "iban": "", "name": "", "taxId": "" }, "source": "", "updatedAt": "2026-09-26T14:03:27Z", "uploadDocument": { "blob": { "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "createdAt": "2026-09-26T14:03:27Z", "id": "44374af9-cacd-40be-8c61-34d6d6e5c09e", "length": 126904, "mime": "application/pdf", "originalFilename": "Rechnung_4711.pdf", "sha256": "25e061231f41488ae299135b3507c724b1b18eaf751b5a705f9322e3c24a4445", "updatedAt": "2026-09-26T14:03:27Z" }, "blobId": "44374af9-cacd-40be-8c61-34d6d6e5c09e", "creatorUserCompanyId": "53cd10a9-c864-4dc3-a777-9860d59efe6c", "ocrFinishedAt": null, "ocrStartedAt": null, "ocrStatus": "pending", "pageCount": 0, "pagesRead": 0 }, "uploadDocumentId": "d7c6a90d-a8e3-4397-a8ec-3d64b03f0c63", "version": ""}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`.
Ort aus PLZ, PLZ aus Ort GET
Liefert für Deutschland und Österreich die Orte einer Postleitzahl (`cities`) oder die Postleitzahlen eines Orts (`postalCodes`), wie die Vorschläge im Kontakt der App; mit beiden Parametern kommt beides. Kennt das Land die PLZ nicht, das andere aber schon, nennt `elsewhere` dieses Land, etwa Österreich für 4020. Die Listen sind nicht vollständig, Großkunden- und Postfach-PLZ fehlen oft. Eine unbekannte PLZ ist deshalb kein Fehler, die Listen bleiben dann leer. Für andere Länder kommt `supported: false`. Ohne `postalCode` und `city` antwortet die Route mit `400`. Quellen: für Deutschland OpenStreetMap (ODbL 1.0), für Österreich die RTR-GmbH. Zeigst du die Vorschläge an, nenne `attribution`, bei `osm` mit Link auf https://www.openstreetmap.org/copyright. Benötigt einen Schlüssel mit der Berechtigung `contacts:read` oder `read`.