# Tool-Übersicht, MCP-Version 2026-11-04 (https://developer.bimetrics.de/mcp/tools/2026-11-04)

Rechnungen stornieren, Dokumente per E-Mail senden, Entwürfe löschen, Zuordnungen erweitern, Firmendaten, Rechnungslayouts und Logo ändern und „Zu erledigen“ lesen.

Diese MCP-Version ergänzt die [Werkzeuge der MCP-Version 2026-11-01](/mcp/tools/2026-11-01), mit denselben Lese- und Schreibrechten. Es gilt die Anlage „MCP-Verbindungen“ aus dem [Rechtspaket 2026-11-04-v1](https://bimetrics.de/rechtliches/2026-11-04-v1/avv#anlage-mcp-verbindungen). Für die neuen Werkzeuge ist nach Anlage 2.3 eine neue Freigabe nötig. Bestehende Verbindungen behalten ihren Umfang, bis du neu verbindest.

Die neuen Werkzeuge nutzen dieselben Befehle wie App und REST-API, mit denselben Sperren. Wo MCP strenger ist, steht es dabei. Weiter gilt: Überwiesen wird nichts, und Kontakte, hochgeladene Belege und ausgestellte Rechnungen lassen sich nicht löschen.

## Auf der Freigabeseite

Der Schalter **Ändern wie in der App** nennt neben dem Hochladen von Belegen und dem Festschreiben jetzt auch das Stornieren von Rechnungen und den Versand per E-Mail. Unter **Nie mehr, als du in bimetrics darfst** steht, was nur in der App geht: Bankzugänge, die Bankverbindung der Firma, Kontenrahmen, Versteuerung, Team und Tarif.

## Stornieren und Entwürfe löschen

Nur mit Schreibzugriff:

| Werkzeug | Was es tut |
| --- | --- |
| `prepare_invoice_cancellation` | Legt zu einer ausgestellten Rechnung den Vollstorno (Stornorechnung, Typ 384) als Entwurf an, wie „Stornieren“ in der App. Festgeschrieben und gebucht wird noch nichts. Ein offener Storno-Entwurf derselben Rechnung wird wiederverwendet. Eine bezahlte oder zugeordnete Rechnung lässt sich nicht stornieren (`StornoOriginalMatched`), mindern lässt sie sich mit `create_invoice_correction`. |
| `delete_sales_draft` | Löscht einen offenen Entwurf einer Rechnung, Stornorechnung, eines Angebots oder einer Auftragsbestätigung, wie „Löschen“ in der App, mit der gelesenen Version und `confirmed`. Ausgestellte Belege und Entwürfe von Rechnungskorrekturen bleiben. |

- **Festschreiben:** `preview_sales_document` liefert das `previewToken` auch für einen Storno-Entwurf, `finalize_sales_draft` schreibt ihn damit fest. Das ist unumkehrbar: Der Storno bekommt eine eigene Nummer, bucht Umsatz und Umsatzsteuer des Originals zurück und wird dem Original zugeordnet. Versendet wird nichts.
- **Strenger als die API:** Über MCP entsteht ein Storno immer in zwei Schritten. `POST /api/draft/{id}/cancel` stellt ihn in einem aus.
- `update_sales_draft` ändert keinen Storno-Entwurf. `delete_order_confirmation_draft` bleibt für Entwürfe von Auftragsbestätigungen.

## Per E-Mail senden

In zwei Schritten wie „Per E-Mail senden“ in der App:

| Werkzeug | Was es tut |
| --- | --- |
| `preview_document_mail` | Lesend. Zeigt für eine ausgestellte Rechnung, Stornorechnung, Rechnungskorrektur, ein Angebot, eine Auftragsbestätigung (`targetKind` `draft`) oder eine Mahnung (`reminder`) Absender, Antwortadresse, Empfänger, Betreff, den ganzen Text samt Signatur und Pflichtangaben, die Anhänge, die letzte Sendung (`lastDelivery`) und ob Senden geht. Ohne `to`, `cc`, `subject` und `body` kommt der Vorschlag der App, mit ihnen genau diese Werte. Liefert ein `previewToken`, 15 Minuten gültig. Versendet nichts. |
| `send_document_mail` | Nur mit Schreibzugriff, unumkehrbar. Sendet genau die Werte der Vorschau, mit deren `previewToken`, `confirmed` und `idempotencyKey`. Andere Empfänger, ein anderer Betreff oder Text, andere Anhänge oder ein abgelaufenes Token senden nichts. |

- **Sperren wie in der App:** nur ausgestellte Dokumente, in der Testphase nur mit bestätigter Mail-Adresse. Je Firma gehen höchstens 20 Empfänger am Tag raus, in der Testphase 3, für App, API und MCP zusammen (siehe [Limits](/limits)).
- **Strenger als die App:** Senden nur mit dem Token der Vorschau und `confirmed`, dazu das Schreibbudget der Verbindung. `to` und `cc` nehmen nur reine Adressen wie `name@example.com`, ohne Anzeigenamen. Empfänger aus Dokumenttexten, Mails oder anderen Werkzeugergebnissen übernimmt die Anwendung nicht ohne deine Bestätigung.
- **Ungekürzt:** Die Vorschau zeigt Betreff, Text und Signatur so, wie sie rausgehen, auch Bankdaten. Gesendet wird genau dieser Text.
- **Nur in der App:** Versand-Einstellungen, Vorlagen und Signatur. Die Liste „Gesendet“ liest MCP nicht, den letzten Versand zeigt `lastDelivery`.

## Rechnungssuche, E-Rechnung als XML, Buchungsfelder

Lesend, auch mit Lesefreigabe:

| Werkzeug | Neu |
| --- | --- |
| `search_sales_documents` | Filter `kind`, `status` (`draft`, `issued`), `buyerContactId`, `issueDateFrom` und `issueDateTo`, neueste zuerst, wie die Listen der App |
| `download_sales_document` | `format` `pdf` (Standard) oder `xml`: die E-Rechnung bytegleich aus dem ausgestellten PDF, immer in Teilen über `dataBase64`. XML gibt es nur zu ausgestellten Rechnungen, Stornos und Rechnungskorrekturen. |
| `search_bookings`, `get_booking` | Felder `kind`, `status` (`open`, `finalized`, `changed_after_export`), `exported`, `exportedAt` und `origin`, wie die Buchungsrouten der API |

## Belege berichtigen

`update_document` und `preview_document_change` nennen jetzt, dass sich bei einer ausgestellten Rechnung nur eine fehlende Kategorie einer Position nachtragen lässt, wie in App und API.

## Zuordnung erweitern

`extend_match`, nur mit Schreibzugriff, nimmt weitere Belege oder Umsätze in eine bestehende Zuordnung auf, wie „Zuordnung erweitern“ in der App, etwa die zweite Rate einer Rechnung. Der Aufruf nennt die ganze neue Auswahl: alle bisherigen Teile und mindestens einen neuen. bimetrics ersetzt die Zuordnung durch eine neue mit neuer `matchId` und bucht neu, festgeschriebene Buchungen mit Storno und Neubuchung.

- **Version:** `get_match` liefert dafür `versions`. Sie gehen unverändert als `expectedVersions` mit, dazu ein `idempotencyKey`.
- **Wie die API, strenger als die App:** Zuordnungen mit an DATEV exportierten Buchungen lehnt das Werkzeug ab (`FinalizedBookingsLocked`), `get_match` liefert dann keine `versions`. Mit bestätigtem Skonto (`CashDiscountNotEligible`) oder einem Beleg aus einer Buchungsvorlage (`MatchNotExtendable`) lässt sich eine Zuordnung auch in der App nicht erweitern.
- `create_match` verweist bei einer bestehenden Zuordnung auf `extend_match`. Eine Regel für die automatische Zuordnung lernt bimetrics dabei nicht.

## Firmendaten

`update_company_profile`, nur mit Schreibzugriff, ändert die Firmendaten wie die Einstellungen der App. Es nimmt nur die Felder, die sich ändern, auch einzeln in `address`, `contactInfo`, `accounting` und `invoiceDefaults`: Name, Rechtsform, Anschrift, Kontaktangaben, Geschäftsführung, Steuer- und Registerangaben, weitere Angaben, Nummernkreise, Skonto-Vorgabe, Zahlungsziel, Schlusstext, DATEV-Nummern, Art der Umsätze mit Steuerhinweisen und Rechnungsabgrenzung. Es prüft wie die App und [`PATCH /api/company/`](https://developer.bimetrics.de/reference/company/update-company.md).

- **Version:** `get_company_context` liefert zusätzlich `settings` in der Form von `update_company_profile` und deren `version`. Sie geht als `expectedVersion` mit, dazu `idempotencyKey` und `confirmed`. Die Antwort nennt die neue `version`.
- **Nur in der App:** Kontenrahmen, Versteuerung samt Befreiungsgrund und die Bankverbindung der Firma. Das Werkzeug kennt diese Felder nicht, die Ablehnung nennt das Feld. Firmentexte, die auf Rechnungen stehen, nehmen keine Bankdaten auf, weder eine IBAN noch Wörter wie BIC, Kontonummer oder Bankverbindung (`CompanyTextBankDetails`). Das Logo ändert `prepare_logo_upload`.
- **Rechtsform:** Fehlt sie beim Erfassen einer privaten Zahlung (`PrivatePaymentNeedsLegalForm`), nennt `record_document_payment` als nächsten Schritt, nach der Rechtsform zu fragen und sie mit `update_company_profile` einzutragen.
- Ablehnungen mit nächstem Schritt: `CompanyVersionConflict`, `NumberStartTaken`, `DatevNumberInvalid`.

## „Zu erledigen“ und Monatsstand

`get_open_tasks` liest, was die Startseite der App unter „Zu erledigen“ nennt: Belege prüfen, Zahlungen ohne Beleg, überfällige Rechnungen, nicht zugestellte Mails, ablaufende Bankfreigaben und Mails im Postfach, je Art mit Anzahl und Link in die App. Dazu kommt der Monatsstand des Vormonats und des laufenden Monats, Belege und Zahlungen erledigt und offen, mit `month` für einen bestimmten Monat. Es liefert nur Zahlen, die einzelnen Einträge lesen `search_documents`, `search_transactions` und `search_receivables`. Die Steuerberatung sieht wie auf der Startseite nur die Arbeit des Monats und die Bankfreigaben. Dieselben Zahlen liefert `GET /api/home/tasks`.

## Rechnungslayouts

Dieselben Prüfungen wie im Layout-Editor der App. Ist der Layout-Editor ausgeschaltet, lehnt jedes Layout-Werkzeug mit `LayoutEditorDisabled` ab.

| Werkzeug | Was es tut |
| --- | --- |
| `list_invoice_layouts` | Lesend. Die Layouts der Firma wie unter Einstellungen › Rechnungen, je Layout die Belegarten (`appliesTo`, `*` für alle übrigen) und die aktuelle Version. Mit `catalog: true` dazu, was ein Layout wählen darf: Vorlagen, Rezepte, Eigenschaften mit Spanne und Vorgabe, Belegarten und Bausteine. |
| `get_invoice_layout` | Lesend. Ein Layout mit Spec und aktueller Version, `standard` für das Layout aller Belegarten ohne eigenes. Mit `versions: true` die Versionen, neueste zuerst. |
| `preview_invoice_layout` | Nur mit Schreibzugriff, weil das Bild die Bankverbindung der Firma und bei einem Beleg dessen Empfänger zeigt (sonst `LayoutPreviewForbidden`). Die erste Seite eines Layouts oder einer Version, auch mit ungespeicherten Änderungen, auf Musterdaten oder einem eigenen Beleg. Anwendungen, die Bilder zeigen, bekommen sie als PNG. Gespeichert wird nichts. |
| `create_invoice_layout` | Nur mit Schreibzugriff. Legt ein Layout aus einer Vorlage oder als unzugewiesene Kopie eines eigenen Layouts (`copyOf`) an. Mit Belegart ersetzt die Vorlage sofort deren Zuordnung. Das erste eigene Layout ersetzt den Standard für alle Belegarten. Die neue Zuordnung gilt für neue Belege und offene Entwürfe, die der Firmenzuordnung folgen. Ausgestellte Belege behalten ihr Layout. |
| `update_invoice_layout` | Nur mit Schreibzugriff. Ändert ein Layout wie der Editor, mit höchstens 20 Operationen je Aufruf: `set`, `preset`, `recipe`, `brandColor`, `addBlock`, `moveBlock`, `removeBlock`, `setBlockValue`, `setNote`, `rename` und `restore`. Jede Änderung ist eine neue Version und gilt sofort für neue Belege und offene Entwürfe. `restore` holt einen früheren Stand als neue Version zurück. |
| `assign_invoice_layout` | Nur mit Schreibzugriff. Legt fest, welches Layout für welche Belegart gilt, wie „Gilt für“ in der App, nur mit der gelesenen Zuordnung (`expected`). |
| `archive_invoice_layout` | Nur mit Schreibzugriff. Archiviert ein Layout, das keiner Belegart zugewiesen ist, oder holt es zurück. Gelöscht wird nie. |

- **Sperren wie in der App:** nur Werte aus dem Katalog, Prüfung jeder Änderung, höchstens 200 Versionen je Firma und Stunde, als Hausfarbe jeder Farbcode `#RRGGBB`. Ein Hinweistext nimmt keine Bankdaten, keinen Zahlungsstand, keine Links und keine Mailadressen an. In der App stehen solche Versionen mit „per KI-Assistent“.
- **Strenger als die App:** `baseVersionId` ist Pflicht, außer bei der ersten Änderung einer Firma ohne eigenes Layout (`own: false`), sonst `LayoutVersionConflict`. `setNote` geht nur mit `confirmed: true`, nachdem du genau diesen Text bestätigt hast.
- Ablehnungen mit nächstem Schritt: `LayoutVersionConflict`, `LayoutCheckFailed`, `LayoutProbeFailed`, `LayoutVersionLimit` und `LayoutAssigned`. `LayoutInvalidChange` und `LayoutCheckFailed` nennen den Grund, etwa `layout_note_link`.

## Logo

| Werkzeug | Was es tut |
| --- | --- |
| `get_company_logos` | Lesend. Das aktive Rechnungslogo mit Größe, Auflösung im Logo-Rahmen, Hinweisen und einem offenen Vorschlag, ob sich das Original zurückholen lässt, die Art des App-Zeichens und je Rolle `activeLogoId`. Anwendungen, die Bilder zeigen, bekommen das Rechnungslogo als Bild. |
| `prepare_logo_upload` | Nur mit Schreibzugriff. Ein Upload-Link für genau eine Datei, Rolle `invoice` oder `app`, 15 Minuten gültig: PNG oder JPG bis 2 MB, 200 bis 5000 px. Nur mit `expectedLogoId` (leer ohne Logo) und `confirmed`. Die Datei geht per `PUT` an den Link, nie durch die Unterhaltung. |
| `fix_company_logo` | Nur mit Schreibzugriff. „Mach es passend“: ein Vorschlag ohne Rand und Hintergrund, aktiv wird nichts. Anwendungen, die Bilder zeigen, bekommen ihn als Bild. |
| `apply_company_logo_fix` | Nur mit Schreibzugriff und `confirmed`. `apply` übernimmt den Vorschlag und behält das Original. `dismiss` verwirft den offenen Vorschlag endgültig. `original` holt das angepasste Original zurück und verwirft den zuvor übernommenen Vorschlag endgültig. |
| `remove_company_logo` | Nur mit Schreibzugriff. Löscht das Rechnungslogo oder das eigene App-Zeichen, nur mit `expectedLogoId` und `confirmed`. |

- **Sperren wie in der App:** Format- und Größenprüfung, je Firma und Tag 20 Uploads und 10-mal „Mach es passend“. Ein neues Rechnungslogo gilt sofort für neue Belege und offene Entwürfe, ausgestellte behalten ihres.
- **Strenger als die App:** `confirmed` beim Hochladen, Übernehmen und Löschen, `expectedLogoId` beim Hochladen und Löschen. Hat jemand das Logo inzwischen in der App gewechselt, lehnt bimetrics mit `LogoChanged` ab und ersetzt oder löscht nichts.

## Teure Aufrufe

`preview_document_mail`, `preview_invoice_layout`, `create_invoice_layout`, `update_invoice_layout` und `fix_company_logo` zählen wie `download_sales_document` zu den teuren Aufrufen: zusammen höchstens 10 je Minute und Verbindung, einer gleichzeitig je Unternehmen (siehe [Limits](/mcp/tools#limits)). Für alle Schreibwerkzeuge gilt dazu das [Schreibbudget](/mcp/write-access#wiederholungen-versionen-und-protokoll).