# Zahlungen für mehrere Belege eintragen (https://developer.bimetrics.de/reference/matches/record-payments-in-bulk) `POST https://app.bimetrics.de/api/match/payment/bulk` operationId: `recordPaymentsInBulk` · Berechtigung (Scope): `matching:write` · Bereich: Zuordnungen 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`. > **Achtung:** Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert. > > KI-Agenten fragen vor diesem Aufruf beim Nutzer nach. ### Authentifizierung `Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich). ### Parameter | Name | Ort | Pflicht | Typ | Beschreibung | | --- | --- | --- | --- | --- | | `Idempotency-Key` | header | ja | 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. | ### Request-Body (`application/json`) Belege, Zahlungsweg und Probelauf Schema `BulkPaymentRequest`. | Feld | Typ | Beschreibung | | --- | --- | --- | | `documentIds` | Array, kann null sein | IDs der Belege, 1 bis 50. | | `dryRun` | boolean | Nur zeigen, was geschähe; nichts ändern. | | `expectedVersions` | object | 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` | string: `cash`, `private` | cash oder private; das Konto bestimmt der Server, bei private nach der Rechtsform. | | `paidBy` | string | Wer privat bezahlt hat, höchstens 100 Zeichen ohne doppelte Anführungszeichen; bei private Pflicht, sonst nicht erlaubt. Steht im Buchungstext. | ### Beispiel ```sh 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 '{"kind":"and","children":[],"limit":50,"offset":0}' ``` ### Antworten | Status | Beschreibung | Inhalt | | --- | --- | --- | | 200 | Erfolg. | `application/json`: BulkResult | | 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error | | 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error | | 403 | Dem Schlüssel fehlt die Berechtigung für diese Route (`APIKeyPermissionDenied`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error | | 409 | Versionskonflikt (`VersionConflict`), abweichender Inhalt für denselben Idempotency-Key (`IdempotencyConflict`), Dublette (`ContactDuplicate`) oder fachlich gesperrte Änderung. Aktuellen Zustand laden und prüfen; keinen anderen Schlüssel verwenden, um einen Konflikt zu umgehen. | `application/json`: Error | | 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error | | 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error | | 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error | #### Felder der Antwort 200 (`BulkResult`) | Feld | Typ | Beschreibung | | --- | --- | --- | | `change` | Array, kann null sein | Belege, die sich ändern oder geändert haben. | | `dryRun` | boolean | True, wenn nichts geändert wurde. | | `failed` | Array, kann null sein | Belege, die der Server abgelehnt hat oder ablehnen würde oder deren Stand er nicht bestätigen konnte. Eine Ablehnung ändert nichts. | | `notice` | string | Der Satz zu einer Grenze, die Belege aufgehalten hat, falls es einen gibt. | | `reversedFinalizedMonths` | Array | 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, kann null sein | Belege, die bleiben, wie sie sind. | | `totalMinor` | integer | Summe von `change` in Cent. | Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json