Automatische Zuordnung einer Buchungsvorlage schalten
Benötigte Berechtigung:collections:write(Vorlagen und Dauerbuchungen ändern)
Echte Wirkung
/api/document/collection/series/{id}/auto-assignKein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Schaltet ein, dass bimetrics Zahlungen dieser Vorlage von allein zuordnet, oder mit enabled: false wieder aus. Muster ist eine Zahlung, die der Vorlage von Hand zugeordnet wurde (transactionId). Von allein zugeordnet wird nur eine Zahlung auf demselben Bankkonto, mit derselben IBAN und demselben Namen der Gegenpartei, centgenau demselben Betrag und derselben Mandatsreferenz, wenn die Bank eine liefert. Das gilt ab der Wertstellung der Musterzahlung: Beim Einschalten ordnet bimetrics auch die schon offenen Zahlungen ab diesem Tag zu, die genau passen; ältere und solche in Monaten, die schon an DATEV exportiert sind, bleiben Vorschläge. Hatte das Muster ein Mandat, braucht die Zahlung dasselbe. Ist „Aus Zuordnungen lernen“ aus (PUT /api/settings/matching), ordnet bimetrics nichts von allein zu. Alles andere bleibt ein Vorschlag, ebenso eine Rücklastschrift, eine Zahlung nach der letzten Rate und jede Zahlung, sobald sich die Zeilen der Vorlage ändern; eine geänderte Vorlage schaltet die Automatik ab. Eine Darlehensrate mit festen Kosten (Zeilen loan_interest oder loan_fees neben dem Rest) verlangt fixedSplitConfirmed: true, also die Bestätigung, dass die Kosten laut Vertrag bei jeder Rate gleich sind, und lastInstalmentOn. Kosten als Anteil gehen nie. Eine Vorlage mit Vorsteuer verlangt contractConfirmed: true, die Bestätigung, dass der Vertrag oder die Dauerrechnung die Steuer gesondert ausweist, und in contractReference den Vertrag, etwa Datum oder Nummer. Sind Zahlungen dieser Gegenpartei in dieser Höhe schon von Hand anders zugeordnet, lehnt die Route mit dem Grund ambiguous ab. Was nicht passt, ergibt 422 TemplateAutoAssignRefused mit context.reason. Der Schalter ändert keinen Inhalt der Vorlage und geht deshalb auch an Standardvorlagen. expectedUpdatedAt ist Pflicht. Jede Änderung steht mit den bestätigten Werten im Änderungsprotokoll der Vorlage. Eine Wiederholung mit gleichem Idempotency-Key wirkt nicht doppelt.
Benötigt einen Schlüssel mit der Berechtigung collections:write.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
id*stringID des Objekts in dieser Firma (UUID).
uuidIdempotency-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 <= 128application/json- body
Schaltet die automatische Zuordnung einer Buchungsvorlage.
contractConfirmed?booleanBestätigung, dass der Vertrag oder die Dauerrechnung die Vorsteuer der Vorlage gesondert ausweist und bei den Unterlagen liegt. Pflicht bei Vorlagen mit Vorsteuer.
contractReference?stringDer Vertrag, etwa Datum oder Nummer, höchstens 120 Zeichen. Pflicht mit contractConfirmed.
length <= 120enabled?booleantrue schaltet ein, false aus. Zum Ausschalten genügt dieses Feld.
expectedUpdatedAt?stringupdatedAt der gelesenen Vorlage.
date-timefixedSplitConfirmed?booleanBestätigung, dass die festen Kosten laut Vertrag bei jeder Rate gleich sind, also kein Annuitätendarlehen. Pflicht bei Darlehensraten mit festen Kosten.
lastInstalmentOn?Tag der letzten Rate. Pflicht mit fixedSplitConfirmed; spätere Zahlungen bleiben Vorschläge.
transactionId?stringZahlung, die der Vorlage von Hand zugeordnet wurde. Ihr Bankkonto, ihre Gegenpartei, ihr Betrag und ihr Mandat werden das Muster. Pflicht beim Einschalten.
uuidErfolg.
application/json- response
Buchungsvorlage, aus der der Beleg beim Zuordnen eines Umsatzes entstand, z. B. für Bankgebühren oder Gewerbesteuer. Der Betrag richtet sich nach dem Umsatz.
autoAssign?Was der Nutzer für die automatische Zuordnung bestätigt hat; fehlt, solange sie aus ist.
collectionNumber?stringNummer der Buchungsvorlage; wird zur Rechnungsnummer (invoiceNumber) der erzeugten Belege. Ist sie leer, entsteht die Rechnungsnummer aus der Bezeichnung.
companyId?stringID der Firma.
uuidcostCenterId?stringKostenstelle oder Verteilung, die jeder neue Beleg aus der Vorlage bekommt, als ID. Fehlt ohne.
uuidcreatedAt?stringAnlage in bimetrics.
date-timefriendlyName?stringBezeichnung.
id?stringID der Buchungsvorlage.
uuidissuer?Aussteller der erzeugten Belege.
kind?stringBelegart der erzeugten Belege: invoice oder receipt.
"invoice""receipt"positionTemplate?array<>|Vorlagen der Positionen der erzeugten Belege.
recipient?Empfänger der erzeugten Belege.
systemTemplateId?|ID der Standardvorlage von bimetrics, aus der die Buchungsvorlage entstand, z. B. für Gewerbesteuer oder die Gebühren einer Bank; null bei eigenen Vorlagen.
uuidupdatedAt?stringLetzte Änderung.
date-timeuploadDocument?|Die hinterlegte Datei; null ohne Datei.
uploadDocumentId?|ID einer hinterlegten Datei; null ohne Datei.
uuidcurl --fail-with-body "https://app.bimetrics.de/api/document/collection/series/497f6eca-6276-4993-bfeb-53cbbbba6f08/auto-assign" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "collectionNumber": "", "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "createdAt": "2026-01-05T09:00:00Z", "friendlyName": "Bürobedarf", "id": "daadb3cc-c785-41c7-83df-078d3688aae9", "issuer": { "address": "", "customerNumber": null, "iban": "", "name": "Musterbedarf GmbH", "taxId": "" }, "kind": "receipt", "positionTemplate": [ { "additionalInfo": { "freeOfVat": false, "reverseCharge": false }, "category": "office_supplies", "label": "Bürobedarf", "totalFixed": 0, "totalRatio": "100", "vatPercentage": "19" } ], "recipient": { "address": "", "customerNumber": null, "iban": "", "name": "", "taxId": "" }, "systemTemplateId": null, "updatedAt": "2026-01-05T09:00:00Z", "uploadDocument": null, "uploadDocumentId": null}Automatische Zuordnung einer Buchungsvorlage lesen GET
Zeigt, ob die Vorlage passende Zahlungen von allein zugeordnet bekommt (`current`), und die neueste Zahlung, die ihr von Hand zugeordnet wurde (`pattern`). `needsFixedSplit` sagt, dass das Einschalten die feste Aufteilung und die letzte Rate verlangt. `problem` nennt, warum die Vorlage den Betrag nicht von allein buchen kann, mit den Gründen von `TemplateAutoAssignRefused`, oder `linesChanged`. Benötigt einen Schlüssel mit der Berechtigung `read`.
Belege einer Buchungsvorlage lesen GET
Listet die Belege, die aus dieser Buchungsvorlage entstanden sind. Benötigt einen Schlüssel mit der Berechtigung `read`.