# Automatische Zuordnung einer Buchungsvorlage schalten (https://developer.bimetrics.de/reference/templates-and-recurring-bookings/update-document-series-auto-assign)

`PUT https://app.bimetrics.de/api/document/collection/series/{id}/auto-assign`

operationId: `updateDocumentSeriesAutoAssign` · Berechtigung (Scope): `collections:write` · Bereich: Vorlagen und Dauerbuchungen

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

> **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 |
| --- | --- | --- | --- | --- |
| `id` | path | ja | string (uuid) | ID des Objekts in dieser Firma (UUID). |
| `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`)

 

Schema `AutoAssignWrite`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `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`. |
| `enabled` | boolean | `true` schaltet ein, `false` aus. Zum Ausschalten genügt dieses Feld. |
| `expectedUpdatedAt` | string (date-time) | `updatedAt` der gelesenen Vorlage. |
| `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` | NaiveDate | Tag der letzten Rate. Pflicht mit `fixedSplitConfirmed`; spätere Zahlungen bleiben Vorschläge. |
| `transactionId` | string (uuid) | Zahlung, die der Vorlage von Hand zugeordnet wurde. Ihr Bankkonto, ihre Gegenpartei, ihr Betrag und ihr Mandat werden das Muster. Pflicht beim Einschalten. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/document/collection/series/{id}/auto-assign" \
  -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`: DocumentSeries |
| 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 diesen Endpunkt (`APIKeyPermissionDenied`, `context.scope` nennt sie; Berechtigungen sind fest: neuen Schlüssel anlegen, austauschen, alten widerrufen), der Endpunkt ist für API-Schlüssel nicht freigegeben (`APIKeyPermissionDenied` ohne `context.scope`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 404 | Nicht gefunden (`NotFound`). | `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 (`DocumentSeries`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `autoAssign` | SeriesAutoAssign | 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 (uuid) | ID der Firma. |
| `costCenterId` | string (uuid) | Kostenstelle oder Verteilung, die jeder neue Beleg aus der Vorlage bekommt, als ID. Fehlt ohne. |
| `createdAt` | string (date-time) | Anlage in bimetrics. |
| `friendlyName` | string | Bezeichnung. |
| `id` | string (uuid) | ID der Buchungsvorlage. |
| `issuer` | DocumentIssuer | Aussteller der erzeugten Belege. |
| `kind` | string: `invoice`, `receipt` | Belegart der erzeugten Belege: `invoice` oder `receipt`. |
| `positionTemplate` | Array<DocumentPositionTemplate>, kann null sein | Vorlagen der Positionen der erzeugten Belege. |
| `recipient` | DocumentRecipient | Empfänger der erzeugten Belege. |
| `systemTemplateId` | string (uuid), kann null sein | 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. |
| `updatedAt` | string (date-time) | Letzte Änderung. |
| `uploadDocument` | UploadDocument | Die hinterlegte Datei; `null` ohne Datei. |
| `uploadDocumentId` | string (uuid), kann null sein | ID einer hinterlegten Datei; `null` ohne Datei. |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json
