bimetricsEntwickler
Belege

Belege suchen

Als Markdown ansehen

Benötigte Berechtigung:read(Daten lesen)

POST
/api/document/filter

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, höchstens 1000 je Seite.

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

Authentifizierung

AuthentifizierungBearer <token>

Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.

In: header

Request-Body

application/json

Filter, Sortierung und Seite. Dokumentierte Filterattribute: x-bimetrics-filter.

TypeScript-Typen

Typ request body für TypeScript.

Suche mit Filter, Sortierung und Seiten. Der Filterausdruck steht auf oberster Ebene; {} liefert alle Einträge.

Filterattribute

Dokumentiert sind diese Attribute für attribute; für sort nur die als sortierbar markierten. Aufbau des Filters: Filtern und Paginieren.

AttributTypSortierbarBeschreibung
iduuidjaID des Belegs.
kindstringjaBelegart: `invoice` (Ausgangsrechnung) oder `receipt` (Eingangsbeleg).
invoiceDatedatejaRechnungsdatum.
invoiceNumberstringjaRechnungsnummer.
issuer.namestringjaName des Ausstellers.
recipient.namestringjaName des Empfängers.
uploadDocument.ocrStatusstringneinStand der Erkennung: `pending`, `processing`, `success`, `failed` oder `quota_paused`.
createdAtdate-timejaZeitpunkt der Anlage in bimetrics.
updatedAtdate-timejaZeitpunkt der letzten Änderung. Für Abgleiche per Polling: `range` mit `lower` = `updatedAt` des zuletzt gelesenen Belegs minus 5 Minuten Überlappung, sortiert nach `updatedAt`; Belege nach `id` speichern, weil manche doppelt kommen.

Antworten

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl --fail-with-body "https://app.bimetrics.de/api/document/filter" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Content-Type: application/json" \  -d '{"direction":["desc","asc"],"limit":100,"offset":0,"sort":["invoiceDate","id"]}'
{  "items": [    {      "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",          "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",      "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"      },      "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"      },      "uploadDocumentId": "e0ba087b-4b49-4137-8bb8-555a24619eae"    },    {      "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",          "finalized": "2026-09-05T10:41:09Z",          "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",      "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"      },      "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",        "ocrFinishedAt": "2026-08-28T06:15:19Z",        "ocrStartedAt": "2026-08-28T06:15:04Z",        "ocrStatus": "success"      },      "uploadDocumentId": "08f65ded-eef9-4cdf-8954-ace8add6eb53"    }  ],  "limit": 100,  "offset": 0,  "total": 2}

Beleg hochladen POST

Lädt genau eine Datei als neuen Beleg hoch und stößt die Erkennung an. Die Antwort ist ein Array mit genau einem Beleg. Das Formularfeld bestimmt die Belegart: `invoice[]` Ausgangsrechnung, `receipt[]` Eingangsbeleg, `auto[]` Erkennung durch bimetrics. Unterstützt werden PDF, PNG, JPEG und XML-E-Rechnungen. `X-Upload-Request-Id` macht Wiederholungen sicher: Dieselbe ID mit identischer Datei, identischem Dateinamen und Feld liefert denselben Beleg, ohne weiteres Kontingent; dieselbe ID mit anderem Inhalt ergibt `409 UploadRequestConflict`. Für jeden neuen Beleg eine neue ID verwenden. Ist das Belegkontingent ausgeschöpft, wird der Beleg trotzdem gespeichert (`uploadDocument.ocrStatus` = `quota_paused`); dann keinen weiteren Upload mit neuer ID starten. Benötigt einen Schlüssel mit der Berechtigung `upload`.

Beleg lesen GET

Liefert einen Beleg mit erkannten Daten, Positionen, Zuordnung (`match`) und Buchungen. Benötigt einen Schlüssel mit der Berechtigung `read`.