Belege suchen
Benötigte Berechtigung:read(Daten lesen)
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.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
Filter, Sortierung und Seite. Dokumentierte Filterattribute: x-bimetrics-filter.
application/json- body
Suche mit Filter, Sortierung und Seiten. Der Filterausdruck steht auf oberster Ebene; {} liefert alle Einträge.
attribute?stringFilterattribut für eq, in, range und oneof, siehe x-bimetrics-filter der Operation. Groß-/Kleinschreibung und Punkte werden ignoriert.
children?array<>Teilfilter für and, or und not.
direction?|array<>Richtung je Eintrag in sort; Standard asc.
includeDeleted?booleantrue liefert auch gelöschte Einträge, erkennbar an deletedAt, aber nur bei Belegen, Kontakten, Bankkonten, Umsätzen und Buchungen; die übrigen Suchrouten ignorieren das Feld. Ohne das Feld oder mit false nur Einträge, die nicht gelöscht sind. Für Abgleiche von Löschungen mit range auf deletedAt, siehe Delta-Sync.
falsekind?stringArt des Filters: and/or verknüpfen children, not verneint children, eq vergleicht attribute mit value (null prüft auf leer), in sucht value als Text im Attribut (enthält, ohne Groß-/Kleinschreibung), range prüft lower ≤ Attribut ≤ upper (eine Grenze genügt), oneof prüft, ob das Attribut einem Wert der Liste value entspricht. Leer: alle Einträge.
"""and""or""eq""not""in""range""oneof"limit?integerTreffer je Seite. Standard und Höchstwert 1000; größere Werte werden auf 1000 begrenzt.
0 <= value1000lower?unknownUntergrenze für range, einschließlich.
offset?integerAnzahl übersprungener Treffer. Haben mehrere Treffer dieselben Werte in sort, ist ihre Reihenfolge nicht festgelegt, und sie können zwischen zwei Seiten doppelt kommen oder fehlen; id als letztes Attribut in sort oder ein Abgleich mit Überlappung (Delta-Sync) hilft dagegen.
0 <= value <= 10000000sort?|array<string>Attribute, nach denen sortiert wird; nur sortierbare Attribute (sortable in x-bimetrics-filter). Ein Attribut mit sortable: false ergibt 400.
upper?unknownObergrenze für range, einschließlich.
value?unknownVergleichswert: für eq ein Wert oder null, für in ein Text, für oneof eine Liste.
Filterattribute
Dokumentiert sind diese Attribute für attribute; für sort nur die als sortierbar markierten. Aufbau des Filters: Filtern und Paginieren.
| Attribut | Typ | Sortierbar | Beschreibung |
|---|---|---|---|
id | uuid | ja | ID des Belegs. |
kind | string | ja | Belegart: `invoice` (Ausgangsrechnung) oder `receipt` (Eingangsbeleg). |
kindReview | boolean | ja | „Belegtyp prüfen“: `true` findet Belege, deren Belegtyp noch jemand wählen muss. |
invoiceDate | date | ja | Rechnungsdatum. |
invoiceNumber | string | ja | Rechnungsnummer. |
issuer.name | string | ja | Name des Ausstellers. |
recipient.name | string | ja | Name des Empfängers. |
uploadDocument.ocrStatus | string | nein | Stand der Erkennung: `pending`, `processing`, `success`, `failed` oder `quota_paused`. |
costCenterId | uuid | ja | Kostenstelle oder Verteilung des Belegs. `eq` mit `null` findet Belege ohne Kostenstelle. |
createdAt | date-time | ja | Zeitpunkt der Anlage in bimetrics. |
updatedAt | date-time | ja | Zeitpunkt der letzten Änderung, auch einer Zuordnung (`match`). 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. Gelöschte Belege findet dieser Abgleich nicht, siehe `deletedAt`. |
deletedAt | date-time | ja | Zeitpunkt, seit dem der Eintrag als gelöscht gilt; `null`, solange er nicht gelöscht ist. Gelöschte Einträge liefert die Suche nur mit `includeDeleted`. Für Abgleiche per Polling: `includeDeleted` und `range` mit `lower` = `deletedAt` des zuletzt gelesenen gelöschten Eintrags minus 5 Minuten Überlappung, sortiert nach `deletedAt`. Auch ein Beleg, den bimetrics beim Löschen behält, etwa wegen festgeschriebener Buchungen, gilt ab dann als gelöscht. |
Eine Seite der Treffer.
application/json- response
Eine Seite gefundener Belege.
items?array<>|Die Treffer dieser Seite.
limit?|Verwendetes limit.
offset?integerVerwendetes offset.
total?integerAnzahl aller Treffer des Filters.
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", "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": "" }, { "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", "deletedAt": null, "finalized": "2026-09-05T10:41:09Z", "finalizedBy": "export", "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", "deletedAt": null, "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" }, "source": "", "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", "pageCount": 2, "pagesRead": 2 }, "uploadDocumentId": "08f65ded-eef9-4cdf-8954-ace8add6eb53", "version": "" } ], "limit": 100, "offset": 0, "total": 2}Duplikate entfernen POST
Entfernt ausgewählte Duplikat-Einträge, wie „Duplikat löschen“ in der App, höchstens 1000 auf einmal. Beleg, Datei, Buchungen und Zuordnung bleiben. Danach hält keine Kopie mehr den Beleg, wenn das Original gelöscht wird. Ist eine ID unbekannt, antwortet die Route mit `404` und entfernt nichts. Eine Wiederholung mit gleichem Idempotency-Key entfernt nichts doppelt und meldet `replayed`. Benötigt einen Schlüssel mit der Berechtigung `documents:delete`.
Beleg lesen GET
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`.