bimetricsEntwickler
Vorlagen und Dauerbuchungen

Automatische Zuordnung einer Buchungsvorlage lesen

Als Markdown ansehen

Benötigte Berechtigung:read(Daten lesen)

GET
/api/document/collection/series/{id}/auto-assign

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.

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

Antworten

Erfolg.

application/json
  1. response

Automatische Zuordnung einer Buchungsvorlage und die Zahlung, die als Muster dient.

current?

Was bestätigt ist; fehlt, solange die Automatik aus ist.

fixedCostsMinor?integer

Darlehenskosten, die die Vorlage aus jeder Rate bucht, in Cent; 0 ohne.

needsContract?boolean

true, wenn die Vorlage Vorsteuer bucht: Das Einschalten verlangt dann contractConfirmed.

needsFixedSplit?boolean

true, wenn die Vorlage Darlehenskosten von einer anderen Zeile abteilt: Das Einschalten verlangt dann fixedSplitConfirmed und lastInstalmentOn.

pattern?

Neueste Zahlung, die der Vorlage von Hand zugeordnet wurde; fehlt ohne eine solche.

problem?string

Warum die Vorlage den Betrag nicht von allein buchen kann, ein Grund von TemplateAutoAssignRefused. Ist die Automatik an, auch linesChanged (bimetrics hat die Vorlage aktualisiert), ended (nach der letzten Rate), returnDebitOpen (eine offene Rücklastschrift pausiert sie) oder assignedElsewhere (eine gleiche Zahlung wurde seit dem Einschalten anders zugeordnet, auf welchem Weg auch immer). Leer, wenn sie bucht.

problemTemplate?string

Bei taken der Name der anderen Vorlage.

taxMinor?integer

Vorsteuer, die die Vorlage aus der Zahlung bucht, in Cent; 0 ohne.

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"
Beispielantwort
{  "fixedCostsMinor": 0,  "needsContract": false,  "needsFixedSplit": true,  "pattern": {    "amountMinor": -135440,    "bankAccountId": "0b6f2d84-3c1a-4e57-9a20-7d5e8c1f4b62",    "bankAccountName": "Geschäftskonto",    "counterpartyIban": "DE02120300000000202051",    "counterpartyName": "Muster Finanzierung GmbH",    "mandateId": "MANDAT-1",    "transactionId": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",    "valueDate": {      "day": 11,      "month": 11,      "year": 2026    }  },  "taxMinor": 0}

Buchungsvorlage ändern PUT

Ändert eine eigene Buchungsvorlage, wie in der App. Die Änderung gilt ab der nächsten Anwendung, schon erzeugte Belege bleiben, wie sie sind. PUT ändert nur die mitgeschickten Felder. `expectedUpdatedAt` ist Pflicht; hat sich das Objekt seitdem geändert, antwortet die Route mit `409 VersionConflict`. Geprüft wird wie im Formular der App: Bezeichnung, Art `invoice` oder `receipt`, 1 bis 100 Zeilen mit Betrag oder Anteil, Kategorie passend zu Art, Verwendung und Kontenrahmen, Steuersatz 19, 7 oder 0 %, auf Eingangsbelegen auch 9 oder 5,5 %, soweit die Kategorie ihn zulässt, Steuerfall bei 0 % auf Eingangsbelegen und die Gegenpartei der Art, außer alle Kategorien werden direkt gebucht. Verstöße ergeben `400 InvalidBookkeepingChange` mit `context.field`. Bezeichnung, Kategorie und Steuersatz werden nur geprüft, wenn sie neu sind. Eine Kundennummer (`customerNumber`) der Gegenpartei muss zu einem Kontakt der Firma mit diesem Namen gehören, wie bei der Wahl des Kontakts in der App; sonst antwortet die Route mit `400 InvalidBookkeepingChange`. Hat der Kontakt auf dieser Seite kein eigenes Personenkonto, weil seine Nummer bei `receipt` über 29999 oder bei `invoice` über 59999 liegt, folgt `400 InvalidContactWrite`. `context.field` ist dann `issuer.customerNumber` oder `recipient.customerNumber`. Ohne `customerNumber` oder mit `0` buchen die Belege auf das Sammelkonto. Eine gespeicherte Nummer wird erst geprüft, wenn sich Name, Nummer oder Art ändern. Standardvorlagen von bimetrics (`systemTemplateId` gesetzt) lassen sich per API lesen und zuordnen, aber nur in der App ändern oder löschen (`403 DocumentTemplateSystemLocked`). Ausnahme ist die Kostenstelle: Enthält der Body außer `expectedUpdatedAt` nur `costCenterId`, setzt er sie auch an einer Standardvorlage. Ihr Inhalt bleibt, und bimetrics hält ihre Zeilen weiter aktuell. Gelöschte und zur Rechtsform unpassende Vorlagen ergeben `409 DocumentTemplateUnavailable`. Eine Wiederholung mit gleichem Idempotency-Key wirkt nicht doppelt. Benötigt einen Schlüssel mit der Berechtigung `collections:write`.

Automatische Zuordnung einer Buchungsvorlage schalten PUT

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