bimetricsEntwickler
Zuordnungen

Bereits erfolgte Zahlung erfassen

Als Markdown ansehen

Benötigte Berechtigung:matching:write(Belege und Zahlungen zuordnen)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/match/payment

Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.

Dokumentiert eine bereits erfolgte Bar-, Verrechnungs- oder Privatzahlung zu einem Beleg oder bucht mit method rounding den Rest als Rundungsdifferenz und mit method write_off einen Forderungsausfall aus. Standardmäßig ausgeschaltet (manualPaymentsEnabled); erwartet expectedAmountOpenMinor zusätzlich zur Belegversion. Betrag in Cent und Euro oder, mit currency, in der Fremdwährung des Belegs; dann bucht der Server den Euro-Wert am Zahltag und die Kursdifferenz. Das Gegenkonto bestimmt der Server. Erzeugt weder eine Banktransaktion noch einen Zahlungsauftrag.

Benötigt einen Schlüssel mit der Berechtigung matching:write.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

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

Header-Parameter

Idempotency-Key*string

Stabiler 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.

Muster^[!-~]+$
Länge1 <= length <= 128

Request-Body

Bereits erfolgte Zahlung

application/json
  1. body

Dokumentation einer bereits erfolgten Bar-, Verrechnungs- oder Privatzahlung oder Ausbuchen einer Rundungsdifferenz.

amountMinor?integer

Gezahlter Betrag in Hundertsteln von currency (Cent bei EUR), positiv und höchstens der offene Betrag in dieser Währung.

cashBasisConfirmed?boolean

Nur bei write_off und Ist-Versteuerung: Die Rechnung war schon nach Ist versteuert, obwohl ihre Leistung vor diesem Kalenderjahr liegt (BIM-1425). Ohne die Angabe lehnt der Server eine solche Rechnung mit WriteOffNotEligible, detail cash_basis_earlier_year ab. Bei einer Leistung aus diesem Jahr ist sie nicht nötig.

cashBookId?string

Nur mit cash: das Kassenbuch, aus dem das Geld kam oder in das es ging (GET /api/cash-books). Pflicht, sobald die Firma ein Kassenbuch in Gebrauch hat, sonst 400 CashBookRejected. Die Zahlung bucht dann auf dessen Kassenkonto und bekommt einen Eintrag mit Nummer im Kassenbuch; zurücknehmen lässt sie sich danach nur über das Storno im Kassenbuch.

Formatuuid
currency?string

Leer oder EUR für eine Zahlung in Euro; sonst die Fremdwährung des Belegs (ISO 4217), auch solange sein Euro-Betrag fehlt. Eine Zahlung in Belegwährung ist clearing oder private. Sie bucht ihren Euro-Wert am Zahltag und, sobald der Beleg einen Euro-Wert hat, die Kursdifferenz zu ihrem Anteil daran (Aufwand 2151/6881, Ertrag 2661/4847, nicht § 256a HGB, ohne Steuerschlüssel). Ein Beleg nimmt entweder Euro-Zahlungen oder Zahlungen in seiner Währung.

documentId?string

ID des Belegs.

Formatuuid
euroAmountMinor?integer

Nur bei einer Zahlung in Belegwährung: der Euro-Betrag laut Abrechnung (Karte, PayPal) in Cent. Ohne Angabe gilt der EZB-Referenzkurs des Zahltags oder des letzten Arbeitstags davor; gibt es keinen, 409 ExchangeRateMissing.

expectedAmountOpenMinor?|

Zuletzt gelesener remainingPaymentMinor-Wert in Cent; verhindert doppelte Erfassung mit neuem Schlüssel.

expectedVersion?string

Zuletzt gelesener fachlicher Versionsdigest des Belegs.

method?string

cash, clearing, private (nur Eingangsbelege), rounding (der ganze Rest eines schon bezahlten Belegs als Rundungsdifferenz, höchstens 1 € und ein Cent je Zahlung plus einer, ohne Umsatzsteuer) oder write_off (Forderungsausfall einer Ausgangsrechnung mit note, bei Soll-Versteuerung nach § 17 UStG); das Konto bestimmt der Server, bei private nach der Rechtsform.

Wert in"cash""clearing""private""rounding""write_off"
note?string

Nur und Pflicht bei write_off: warum der Rest uneinbringlich ist, höchstens 500 Zeichen.

paidBy?string

Wer privat bezahlt hat, höchstens 100 Zeichen ohne doppelte Anführungszeichen; nur mit private. Steht im Buchungstext.

paidOn?

Tatsächliches Zahlungsdatum, höchstens heute.

Antworten

Erfolg.

application/json
  1. response

Erfasste Zahlung und neuer offener Betrag.

amountOpenMinor?integer

Verbleibender offener Betrag in Cent; solange beim Beleg der Euro-Betrag fehlt, in Hundertsteln der Belegwährung.

amountOpenOriginalMinor?integer

Nur bei einer Zahlung in Belegwährung: was vom Beleg in seiner Währung noch offen ist, in Hundertsteln.

payment?|

Dokumentierte Zahlung.

replayed?boolean

True bei sicherer Wiederholung eines bereits erfolgreichen Aufrufs.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/match/payment" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "amountOpenMinor": 5950,  "payment": {    "account": 1000,    "accountContra": 71007,    "amountMinor": 5950,    "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",    "createdAt": "2026-09-02T10:00:00Z",    "currency": "EUR",    "documentId": "a129ef0a-da5d-4204-804c-764d751bca95",    "id": "d5e264b8-4c4a-4155-a71a-c0bd9d9c757f",    "method": "cash",    "origin": "api",    "paidOn": {      "day": 2,      "month": 9,      "year": 2026    },    "updatedAt": "2026-09-02T10:00:00Z"  },  "replayed": false}

Ausgeblendeten Vorschlag zurückholen DELETE

Holt eine ausgeblendete Kombination zurück, wie das Rückgängig nach „Vorschlag ausblenden“ in der App: Sie erscheint wieder, und die automatische Zuordnung darf genau diese Kombination wieder nehmen. Es wird nichts zugeordnet oder gebucht. Eine Wiederholung mit demselben `Idempotency-Key` ändert nichts; gibt es die Kombination in dieser Firma nicht (mehr), antwortet die Route sonst mit `404`. Benötigt einen Schlüssel mit der Berechtigung `matching:write`.

Zahlungen für mehrere Belege eintragen POST

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`.