Zahlungen für mehrere Belege eintragen
Benötigte Berechtigung:matching:write(Belege und Zahlungen zuordnen)
Echte Wirkung
/api/match/payment/bulkKein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Dokumentiert für Eingangsbelege eine bereits erfolgte Bar- oder Privatzahlung, wie „Zahlung eintragen“ in der Mehrfachauswahl der App: je Beleg der volle offene Betrag, Zahltag ist das Belegdatum, bei einem Datum in der Zukunft heute. Geld bewegt sich nicht, es entsteht weder eine Banktransaktion noch ein Zahlungsauftrag. Standardmäßig ausgeschaltet (403 ManualPaymentUnavailable). Übersprungen werden wie in der App alles außer Eingangsbelegen (kind), Gutschriften (credit), stornierte Belege (deleted), Belege aus Dauerbuchungen oder Vorlagen (linked), Sammelzuordnungen (collective), an DATEV exportierte (exported), teilweise bezahlte (partial), bezahlte (paid), mit Buchungsfehlern (issues), noch nicht gelesene (reading), ungebuchte (unbooked), ohne Betrag (noAmount) oder ohne Datum (noDate). Dazu notFound und notPreviewed. Eine einzelne Zahlung nimmst du mit POST /api/match/payment/reverse zurück. Höchstens 50 Belege je Aufruf (400 BulkLimitExceeded). Die Antwort nennt je Beleg, was geschah: change geändert, skipped mit Grund übersprungen, failed mit Code abgelehnt. Das ist ein Teilerfolg wie in der App: Ein abgelehnter Beleg hält die anderen nicht auf, und die Route antwortet mit 200. Mit dryRun ändert sie nichts und zeigt, was geschähe, mit einer version je Beleg. Zum Ausführen gibst du diese als expectedVersions zurück, sonst antwortet die Route mit 400 ExpectedVersionRequired. Es ändert sich nur, was unter change stand und seitdem unverändert ist: Ein geänderter Beleg kommt mit VersionConflict in failed, die übrigen laufen, und ein Beleg ohne Eintrag bleibt mit notPreviewed in skipped. Jeder Beleg läuft als eigener Befehl mit eigenem Eintrag im Protokoll und zählt einzeln auf die Tagesgrenzen der Firma und der Testphase. Der ganze Aufruf zählt einmal auf die Grenzen je Minute. Eine Wiederholung mit gleichem Idempotency-Key ändert nichts doppelt und erledigt, was noch offen ist. Sie klärt auch den Stand, wenn ein Aufruf abbricht: OutcomeUnknown heißt, der Beleg kann schon gebucht sein.
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 <= 128Belege, Zahlungsweg und Probelauf
application/json- body
Eingangsbelege und der Weg, auf dem sie schon bezahlt wurden.
documentIds?array<>|IDs der Belege, 1 bis 50.
dryRun?booleanNur zeigen, was geschähe; nichts ändern.
expectedVersions?Ohne dryRun Pflicht: die version aus change eines dryRun je Beleg-ID. Es ändert sich nur, was seitdem unverändert ist; ein Beleg ohne Eintrag bleibt (notPreviewed).
method?stringcash oder private; das Konto bestimmt der Server, bei private nach der Rechtsform.
"cash""private"paidBy?stringWer privat bezahlt hat, höchstens 100 Zeichen ohne doppelte Anführungszeichen; bei private Pflicht, sonst nicht erlaubt. Steht im Buchungstext.
Erfolg.
application/json- response
Was mit jedem Beleg geschah oder bei dryRun geschähe.
change?array<>|Belege, die sich ändern oder geändert haben.
dryRun?booleanTrue, wenn nichts geändert wurde.
failed?array<>|Belege, die der Server abgelehnt hat oder ablehnen würde oder deren Stand er nicht bestätigen konnte. Eine Ablehnung ändert nichts.
notice?stringDer Satz zu einer Grenze, die Belege aufgehalten hat, falls es einen gibt.
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.
skipped?array<>|Belege, die bleiben, wie sie sind.
totalMinor?integerSumme von change in Cent.
curl --fail-with-body "https://app.bimetrics.de/api/match/payment/bulk" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "change": [ { "amountMinor": 11900, "counterparty": "Beispiel Bürobedarf GmbH", "id": "a129ef0a-da5d-4204-804c-764d751bca95", "invoiceNumber": "RE-2026-0142", "paidOn": { "day": 10, "month": 10, "year": 2026 }, "paymentId": "3432135f-5b01-4288-9764-e1ff7d061777" } ], "dryRun": false, "failed": [], "skipped": [ { "id": "3026096b-614f-40d3-8749-8acf9b529480", "reason": "kind" } ], "totalMinor": 11900}Bereits erfolgte Zahlung erfassen POST
Dokumentiert eine bereits erfolgte Bar-, Verrechnungs- oder Privatzahlung zu einem Beleg. Standardmäßig ausgeschaltet (manualPaymentsEnabled); erwartet expectedAmountOpenMinor zusätzlich zur Belegversion. Betrag in Cent, Währung EUR. Das Gegenkonto bestimmt der Server. Erzeugt weder eine Banktransaktion noch einen Zahlungsauftrag. Benötigt einen Schlüssel mit der Berechtigung `matching:write`.
Privat bezahlt: Stand der Firma lesen GET
Sagt, wie bimetrics eine private Zahlung (`recordPayment` mit `method` `private`) für diese Firma bucht, und bei GmbH und UG, was die Firma dem Gesellschafter noch schuldet. Den Zahlungsstand eines einzelnen Belegs liefert `getDocument` (`remainingPaymentMinor`, `recordedPayments`). Nur mit eingeschalteter Zahlungserfassung (`manualPaymentsEnabled`), sonst `403 ManualPaymentUnavailable`. Benötigt einen Schlüssel mit der Berechtigung `read`.