# Automatisierung auf vorhandene Belege anwenden (https://developer.bimetrics.de/reference/automations/apply-automation-to-existing)

`POST https://app.bimetrics.de/api/agent-rule-group/{id}/apply-existing`

operationId: `applyAutomationToExisting` · Berechtigung (Scope): `documents:write` · Bereich: Automatisierungen

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

> **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 der Automatisierung 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`)

Probelauf, Belege und Versionen

Schema `AutomationApplyRequest`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `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<string (uuid)> | 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` | object | 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`). |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/agent-rule-group/{id}/apply-existing" \
  -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`: AutomationApplyResult |
| 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 |
| 402 | Der Tarif der Firma enthält keine Automatisierungen (`PlanRequired`, `context.gate` ist `feature_rules`, `context.nextStep` nennt den Weg zum passenden Tarif). Nach einem Tarifwechsel erneut senden. | `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 (`AutomationApplyResult`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `change` | Array<BulkChange>, kann null sein | 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<BulkFailure>, kann null sein | 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<BulkSkip>, kann null sein | Die gesendeten `documentIds`, die bleiben, wie sie sind, mit Grund. |
| `skippedCounts` | object, kann null sein | Belege, die bleiben, wie sie sind, je Grund, auch die, die das Suchen nicht einzeln nennt. |
| `totalMinor` | integer | Summe von `change` in Cent. |

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