bimetricsEntwickler
Automatisierungen

Automatisierung auf vorhandene Belege anwenden

Als Markdown ansehen

Benötigte Berechtigung:documents:write(Nicht an DATEV exportierte Belege ändern)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/agent-rule-group/{id}/apply-existing

Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.

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.

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 der Automatisierung 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

Probelauf, Belege und Versionen

application/json
  1. body

Probelauf oder Übernahme einer Automatisierung auf vorhandenen Belegen.

cursor?string

Nur beim dryRun ohne documentIds: cursor des vorigen dryRun, um die Belege danach zu prüfen. Belege davor kommen nicht wieder.

documentIds?array<>

Ohne dryRun Pflicht: die bestätigten Belege aus change des dryRun, 1 bis 50. Mit dryRun prüft er nur diese, statt zu suchen.

dryRun?boolean

Nur zeigen, was geschähe; nichts ändern.

expectedVersions?

Ohne dryRun Pflicht: die version aus change eines dryRun je Beleg-ID. Es ändert sich nur, was seitdem unverändert ist; ein Beleg ohne Eintrag bleibt (notPreviewed).

Antworten

Erfolg.

application/json
  1. response

Was mit jedem Beleg geschah oder bei dryRun geschähe.

change?array<>|

Belege, die sich ändern oder geändert haben, beim Suchen höchstens 50.

cursor?string

Setzt den dryRun nach den geprüften Belegen fort, solange more über 0 liegt.

dryRun?boolean

True, wenn nichts geändert wurde.

failed?array<>|

Belege, die der Server abgelehnt hat oder ablehnen würde oder deren Stand er nicht bestätigen konnte. Eine Ablehnung ändert nichts.

more?integer

Weitere Belege nach diesen, die sich ändern würden; ein dryRun mit cursor prüft sie.

notice?string

Der Satz zu einer Grenze, die Belege aufgehalten hat, falls es einen gibt.

reversedFinalizedMonths?array<string>

Bleibt leer: Eine Automatisierung storniert nie einen festgeschriebenen Monat.

skipped?array<>|

Die gesendeten documentIds, die bleiben, wie sie sind, mit Grund.

skippedCounts?|

Belege, die bleiben, wie sie sind, je Grund, auch die, die das Suchen nicht einzeln nennt.

totalMinor?integer

Summe von change in Cent.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/agent-rule-group/497f6eca-6276-4993-bfeb-53cbbbba6f08/apply-existing" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "change": [    {      "amountMinor": 11900,      "categoryAfter": "rent_ancillary_costs",      "categoryBefore": "office_supplies",      "counterparty": "Muster Werkstatt GmbH",      "id": "a129ef0a-da5d-4204-804c-764d751bca95",      "invoiceNumber": "PRO-2026-0042",      "kindAfter": "receipt",      "kindBefore": "receipt",      "taxChanges": [        {          "index": 0,          "vatPercentageAfter": "0",          "vatPercentageBefore": "0",          "vatTreatmentAfter": "freeOfVat",          "vatTreatmentBefore": "none"        }      ],      "version": "4f2a9c1e7b3d"    }  ],  "dryRun": true,  "failed": [],  "more": 0,  "skipped": [],  "skippedCounts": {    "exported": 1,    "finalized": 3  },  "totalMinor": 11900}

Automatisierung ändern oder schalten PUT

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

Feedback an bimetrics senden POST

Sendet Feedback zu bimetrics an das bimetrics-Team, wie `send_feedback` per MCP: was du vorhattest, was geklappt hat, was nicht und was besser werden soll. In deiner Firma ändert sich nichts. Pflicht sind `outcome` und `intent` mit 3 bis 300 Zeichen, dazu mindestens eines von `wentWell`, `wentWrong` und `improve` mit je höchstens 2000 Zeichen. Fehlt ein Text oder steht nur ein Fülltext wie „test“ darin, antwortet die Route mit `400 FeedbackEmpty`. Ein ungültiges Feld ergibt `400 BadRequest`, `context.field` nennt es. `refs` nennt höchstens 10 betroffene Pfade oder Werkzeuge, etwa `/api/document/filter` oder `search_documents`. Texte mit E-Mail-Adressen, Links, IBANs oder unsichtbaren Steuerzeichen lehnt die Route mit `400 UnsafeMCPText` ab, `context.reason` nennt den Grund: `mail`, `link`, `iban` oder `control`. Bitte keine Namen von Kunden, Lieferanten oder Mitarbeitenden, keine Beträge und keine Beleginhalte. Je Firma gehen höchstens 10 Meldungen in 24 Stunden (API und MCP zusammen), je Schlüssel 3 in einer Stunde. Danach antwortet die Route mit `429 FeedbackLimit` und speichert nichts; der Header `Retry-After` nennt die Sekunden, bis wieder eine Meldung geht. Kommt dasselbe Feedback innerhalb von 10 Minuten noch einmal, speichert bimetrics es nicht doppelt und antwortet mit der gespeicherten `id` und `replayed: true`. Einen Idempotency-Key braucht die Route nicht. bimetrics löscht Feedback nach 180 Tagen, mit der Firma auch früher. Benötigt einen Schlüssel mit der Berechtigung `read`.