bimetricsEntwickler
Vorlagen und Dauerbuchungen

Automatische Zuordnung einer Buchungsvorlage schalten

Als Markdown ansehen

Benötigte Berechtigung:collections:write(Vorlagen und Dauerbuchungen ändern)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
put/api/document/collection/series/{id}/auto-assign

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

Authentifizierung

headerAuthentifizierungBearer <bm_…>

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

Pfadparameter

id*string

ID des Objekts in dieser Firma (UUID).

Formatuuid

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

application/json
  1. body

Schaltet die automatische Zuordnung einer Buchungsvorlage.

contractConfirmed?boolean

Bestätigung, dass der Vertrag oder die Dauerrechnung die Vorsteuer der Vorlage gesondert ausweist und bei den Unterlagen liegt. Pflicht bei Vorlagen mit Vorsteuer.

contractReference?string

Der Vertrag, etwa Datum oder Nummer, höchstens 120 Zeichen. Pflicht mit contractConfirmed.

Längelength <= 120
enabled?boolean

true schaltet ein, false aus. Zum Ausschalten genügt dieses Feld.

expectedUpdatedAt?string

updatedAt der gelesenen Vorlage.

Formatdate-time
fixedSplitConfirmed?boolean

Bestä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?string

Zahlung, die der Vorlage von Hand zugeordnet wurde. Ihr Bankkonto, ihre Gegenpartei, ihr Betrag und ihr Mandat werden das Muster. Pflicht beim Einschalten.

Formatuuid

Antworten

Erfolg.

application/json
  1. 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?string

Nummer der Buchungsvorlage; wird zur Rechnungsnummer (invoiceNumber) der erzeugten Belege. Ist sie leer, entsteht die Rechnungsnummer aus der Bezeichnung.

companyId?string

ID der Firma.

Formatuuid
costCenterId?string

Kostenstelle oder Verteilung, die jeder neue Beleg aus der Vorlage bekommt, als ID. Fehlt ohne.

Formatuuid
createdAt?string

Anlage in bimetrics.

Formatdate-time
friendlyName?string

Bezeichnung.

id?string

ID der Buchungsvorlage.

Formatuuid
issuer?

Aussteller der erzeugten Belege.

kind?string

Belegart der erzeugten Belege: invoice oder receipt.

Wert in"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.

Formatuuid
updatedAt?string

Letzte Änderung.

Formatdate-time
uploadDocument?|

Die hinterlegte Datei; null ohne Datei.

uploadDocumentId?|

ID einer hinterlegten Datei; null ohne Datei.

Formatuuid
Beispielanfrage
curl --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 '{}'
Beispielantwort
{  "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}