Belege und Umsätze zuordnen
Benötigte Berechtigung:matching:write(Belege und Zahlungen zuordnen)
Echte Wirkung
/api/match/Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Ordnet vorhandene Belege und Bankumsätze zu. Alle IDs müssen zur Firma gehören. Ist ein Beleg oder Umsatz schon zugeordnet, antwortet die API mit 409 MatchConflict. Mit expectedVersions stellst du sicher, dass sich kein Beleg seit dem Lesen geändert hat: Nenne darin jeden gewählten Beleg mit seiner version aus GET /api/document/{id}. Bankumsätze und Buchungsvorlagen haben keine lesbare Version und gehören nicht hinein. Die Änderung erzeugt vorbereitete Buchungen. Ob sie fehlerfrei sind, zeigt bookingErrors, wenn du den Beleg danach erneut liest. Haben Belege oder Umsätze schon an DATEV exportierte Buchungen, antwortet die API mit 409 FinalizedBookingsLocked und nennt in context.exportedMonths die Monate. Zeig dem Nutzer diese Monate. Hat er bestätigt, sende die Anfrage noch einmal mit confirmExported: true. bimetrics bucht dann wie die App: Storno und Neubuchung nur dort, wo sich etwas ändert; beides geht mit dem nächsten Export der noch nicht exportierten Buchungen als Nachtrag an DATEV.
Benötigt einen Schlüssel mit der Berechtigung matching:write.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
Idempotency-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 <= 128IDs der gewählten Belege, Umsätze und Buchungsvorlagen
application/json- body
Vorhandene Belege und Umsätze zuordnen.
bookRounding?booleantrue nur auf ausdrücklichen Wunsch des Nutzers, wie „Zuordnen und Rundung ausbuchen“ in der App: bimetrics bucht den Rest, den die Zuordnung an ihrem einen Beleg offen lässt, im selben Vorgang als Rundungsdifferenz aus, genau wie POST /api/match/payment mit method rounding. Der ganze Rest, höchstens 1 € und ein Cent je Zahlung des Belegs plus einer, mit dem heutigen Datum, ohne Geldbewegung und ohne Umsatzsteuer; der Beleg gilt danach als bezahlt. Genau ein Beleg, nicht in Fremdwährung und nicht bei einer Abschlagsrechnung. Ist der Rest keine Rundung, antwortet die API mit 400 RoundingNotEligible (Grund in detail) und legt nichts an, auch die Zuordnung nicht. Zurück geht es mit POST /api/match/payment/reverse für die Rundung, danach DELETE /api/match/{id}.
category?stringOptionale Zuordnungskategorie.
confirmCashDiscount?booleanBewusste Bestätigung der ermittelten Skontodifferenz.
confirmExported?booleantrue nur, nachdem der Nutzer die Monate aus context.exportedMonths einer Ablehnung mit 409 FinalizedBookingsLocked gesehen und bestätigt hat. Dann ordnet bimetrics auch Belege und Umsätze mit schon an DATEV exportierten Buchungen zu, wie die App.
confirmReminderCharges?booleanBewusste Bestätigung, den Mehrbetrag der Zahlung als Mahnkosten und Zinsen zu buchen, wie reminderCharges der Vorschau ihn nennt. Nicht zusammen mit confirmCashDiscount.
documentIds?array<>|IDs bestehender Belege.
documentSeriesIds?array<>IDs anzuwendender Buchungsvorlagen.
expectedVersions?Optional: je gewähltem Beleg seine version aus GET /api/document/{id}, nach Beleg-ID. Fehlt ein gewählter Beleg oder hat er sich geändert, kommt 409 VersionConflict. Bankumsätze und Buchungsvorlagen gehören nicht hinein.
transactionIds?array<>|IDs bestehender Bankumsätze.
Erfolg.
application/json- response
Ergebnis der Zuordnung.
match?|Gespeicherte Zuordnung.
replayed?booleanTrue, wenn der frühere Erfolg dieses Idempotency-Key zurückgegeben wird.
reversedFinalizedMonths?array<string>Monate (YYYY-MM), in denen bimetrics festgeschriebene Buchungen storniert und mit geändertem Datum, Leistungszeitraum, Konto, Steuerkennzeichen oder Betrag neu gebucht hat. Ändert sich nur der Buchungstext oder die Zuordnung, fehlt der Monat. Hast du die Umsatzsteuer-Voranmeldung für einen dieser Monate oder, bei geändertem Datum, für den neuen Monat schon abgegeben, musst du sie womöglich berichtigen. Fehlt, wenn nichts storniert wurde, und bei einer Wiederholung mit demselben Idempotency-Key.
curl --fail-with-body "https://app.bimetrics.de/api/match/" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "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" }, "replayed": false}Buchungsvorlagen suchen POST
Sucht die Buchungsvorlagen der Firma, etwa für Gewerbesteuer, Bankgebühren oder Privatentnahmen. Ihre IDs nimmt `createMatch` in `documentSeriesIds`: bimetrics legt beim Zuordnen eines Umsatzes aus der Vorlage einen Beleg an. Wie in der App fehlen Vorlagen, die zur Rechtsform nicht passen, und solche, die zum Löschen vorgemerkt sind. Benötigt einen Schlüssel mit der Berechtigung `read`.
Korrekturguthaben mit anderer Rechnung verrechnen POST
Verrechnet einen positiven Betrag in EUR-Cent mit einer geeigneten offenen Rechnung desselben Kunden. expectedRevision und expectedTargetRevision müssen beide aktuell sein. Der Betrag ist auf refundAvailableMinor und den offenen Zielbetrag begrenzt. Erzeugt atomar eine negative Zahlung zum Korrekturbeleg und eine gleich hohe positive Zahlung zur Zielrechnung, verbunden durch settlementPairId. Keine Banktransaktion, kein Zahlungsauftrag; die ausgestellten Dokumente bleiben unverändert. Benötigt einen Schlüssel mit der Berechtigung `matching:write`.