Automatisierung ändern oder schalten
Benötigte Berechtigung:automations:write
Echte Wirkung
/api/agent-rule-group/{id}Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Ersetzt Name, active und alle Regeln; eine Regel, die fehlt, entfällt. Zum Ausschalten schick die Automatisierung so, wie du sie gelesen hast, mit active: false; zum Einschalten ebenso mit active: true. expectedUpdatedAt ist das gelesene updatedAt und Pflicht; hat sich die Automatisierung seitdem geändert, antwortet die Route mit 409 VersionConflict und ändert nichts. Eine feste Regel braucht mindestens eine Bedingung und eine Kategorie (targetCategory), mode ist all oder any. setKind geht nur zusammen mit einer Kategorie, die zu diesem Belegtyp passt. Kategorien, die bimetrics nur selbst setzt oder die es nur für Buchungen ohne Beleg gibt, lässt eine feste Regel nicht zu. Prüft sie den Belegtyp (match.kind), ohne ihn zu setzen, muss die Kategorie zu diesem Belegtyp passen. Bereits gespeicherte Regeln mit derselben id bleiben erlaubt, solange targetCategory, setKind und match.kind unverändert sind. Verstößt eine Regel dagegen, antwortet die Route mit 400, context.field nennt das Feld (etwa rules[0].targetCategory) und detail den Satz der App; gespeichert wird nichts. Höchstens 100 Automatisierungen sind gleichzeitig aktiv, eine weitere aktive ergibt 409 AgentRuleGroupActiveLimit. Jede Regel bekommt eine id; schick sie beim Ändern mit, damit ihre Treffer bei ihr bleiben. Bei einer Wiederholung schickst du denselben Idempotency-Key.
Benötigt einen Schlüssel mit der Berechtigung automations:write.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
id*stringID der Automatisierung 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
Eine Automatisierung mit allen Regeln, wie sie gespeichert werden soll.
active?booleantrue: Ihre Regeln wirken auf neue Uploads und Korrekturen. Höchstens 100 Automatisierungen sind gleichzeitig aktiv.
displayName?stringName der Automatisierung.
expectedUpdatedAt?stringupdatedAt der gelesenen Automatisierung, beim Ändern Pflicht.
date-timerules?array<>|Alle Regeln; beim Ändern ersetzen sie die bisherigen.
Erfolg.
application/json- response
Eine Automatisierung mit ihren Regeln.
active?booleantrue: Ihre Regeln wirken auf neue Uploads und Korrekturen.
companyId?stringID der Firma.
uuidcreatedAt?stringZeitpunkt des Anlegens.
date-timedisplayName?stringName der Automatisierung.
id?stringID der Automatisierung.
uuidrules?array<>|Die Regeln der Automatisierung.
updatedAt?stringZeitpunkt der letzten Änderung; beim Ändern als expectedUpdatedAt zurückschicken.
date-timecurl --fail-with-body "https://app.bimetrics.de/api/agent-rule-group/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "active": true, "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "createdAt": "2026-11-20T09:00:00Z", "displayName": "Eigene Rechnungen", "id": "3f6a9d21-4c8e-4b7a-9e15-8d2c7b4a1f60", "rules": [ { "active": true, "id": "a81c5e3d-92f4-4d6b-b07e-5c3f1a9e2d47", "instructions": "", "isOverride": false, "match": { "invoiceNumberPrefixes": [ "PRO-2026" ], "mode": "any", "ownCompany": true }, "name": "Eigene Rechnungen sind Ausgang", "priority": 1, "scope": "categorization", "setKind": "invoice", "targetCategory": "sales_income", "triggerWords": [], "weight": 85 } ], "updatedAt": "2026-11-20T09:00:00Z"}Automatisierung löschen DELETE
Löscht eine Automatisierung wie in der App; das Änderungsprotokoll behält sie. Belege, die ihre Regeln schon geändert haben, bleiben, wie sie sind. Wer sie nur pausieren will, schickt sie mit `PUT` so, wie er sie gelesen hat, mit `active: false`. Bei einer Wiederholung schickst du denselben Idempotency-Key. Benötigt einen Schlüssel mit der Berechtigung `automations:write`.
Automatisierung auf vorhandene Belege anwenden POST
Wendet die festen Regeln einer Automatisierung auf Belege an, die es schon gibt, wie „Auf vorhandene Belege anwenden“ in der App. Die Automatisierung muss aktiv sein und eine aktive feste Regel haben, sonst `400` mit `context.field` `id`. Es entscheiden alle aktiven festen Regeln der Firma zusammen, wie beim Upload: Eine andere Automatisierung kann den Belegtyp setzen, und wollen zwei Regeln Verschiedenes, bleibt der Beleg (`ruleConflict`). Eine Regel dieser Automatisierung muss treffen (`noMatch`). Anders als beim Upload kann sie auch einen Belegtyp ändern, den jemand selbst gewählt hat; die Vorschau zeigt jeden Wechsel, und geändert wird nur, was bestätigt ist. Jede Position bekommt die Kategorie, mit dem Steuersatz, den die Kategorie erlaubt, sonst ihren Vorgaben. Ohne `documentIds` sucht der `dryRun` selbst: Belege der letzten 12 Monate, nicht gelöscht, neueste zuerst. Bis zu 50, die sich ändern, stehen in `change`, mit Belegtyp und Kategorie vorher und nachher und `taxChanges`; was bleibt, zählt `skippedCounts` je Grund. `more` zählt weitere Belege, die sich ändern würden, ein `dryRun` mit `cursor` prüft sie. Gründe: festgeschriebene Belege und solche, deren Änderung einen festgeschriebenen Monat stornieren würde (`finalized`), ausgestellte Rechnungen (`issued`), an DATEV exportierte (`exported`), aus Dauerbuchungen oder Vorlagen (`linked`), mit erfasster Zahlung (`paid`), einer Zahlung oder anderen Belegen zugeordnete, deren Belegtyp die Regel wechseln würde (`matched`), noch nicht gelesene (`unread`), Reverse Charge neben der Steuerbehandlung der Kategorie (`reverseCharge`), Belege, die schon so stehen (`unchanged`), mit offenem Belegtyp (`kindReview`), zu deren Typ die Kategorie nicht passt (`otherKind`), ohne Positionen (`other`), stornierte (`deleted`), die `PATCH /api/document/{id}` ablehnen würde (`refused`, nur beim Suchen), dazu `noMatch`, `ruleConflict`, `notFound` und `notPreviewed`. Zum Übernehmen schickst du die bestätigten `documentIds` aus `change` mit ihren `expectedVersions`, ohne `documentIds` antwortet die Route mit `400` und `context.field` `documentIds`. Die Version deckt auch die Wirkung der Regeln ab: Hat sich eine Regel seitdem geändert, kommt der Beleg mit `VersionConflict` in `failed`. Jeder Beleg ändert sich mit `PATCH /api/document/{id}`, das Protokoll nennt den Schlüssel. Ein API-Schlüssel braucht `documents:write` und zusätzlich `automations:read`, sonst `403 APIKeyPermissionDenied`. Der Aufruf zählt zum Budget der Pool-Lesungen wie `POST /api/agent-rule-group/preview`. 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 `documents:write`.