# Tool-Übersicht, Fassung 2026-10-11 (https://developer.bimetrics.de/mcp/tools/2026-10-11) Forderungsstände, Mahnungen, Rechnungskorrekturen mit Erstattungen und Verrechnungen sowie wiederkehrende Rechnungsentwürfe. Diese Fassung ergänzt die [Werkzeuge vom 10.10.2026](/mcp/tools/2026-10-10). Es gilt weiterhin das [Rechtspaket 2026-10-09-v1](https://bimetrics.de/rechtliches/2026-10-09-v1/avv#anlage-mcp-verbindungen). Für den erweiterten Werkzeug- und Datenumfang ist nach Anlage 2.3 eine neue Freigabe erforderlich. Bestehende Verbindungen erhalten keine zusätzlichen Werkzeuge oder Schreibrechte. ## Forderungen und Mahnungen Eine Lesefreigabe umfasst diese zusätzlichen Werkzeuge: | Werkzeug | Inhalt | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `search_receivables`, `get_receivable` | Aktuelle Forderung mit Zahlungen, ausgestellten Korrekturen und `receivableVersion`. `paymentKnown: false` bedeutet, dass der Zahlungsstand nicht eindeutig bestimmt werden kann. | | `search_payment_reminders`, `get_payment_reminder` | Mahnungsentwürfe, ausgestellte und zurückgezogene Mahnungen mit Status und Versionswert. | | `preview_payment_reminder` | Tatsächliches PDF; bei Entwürfen auf Basis des heutigen Forderungsstands, bei ausgestellten Dokumenten aus dem unveränderlichen Original. Größere PDFs kommen in Abschnitten, nicht als einzelne Bildseiten. | | `download_payment_reminder` | Vollständiges ausgestelltes Original-PDF, auch nach Zurückziehen der Mahnung. Große Dateien werden wie bei `download_sales_document` in geprüften Abschnitten übertragen. | Mit ausdrücklich freigegebenem Schreibzugriff kommen `create_payment_reminder`, `update_payment_reminder`, `issue_payment_reminder` und `change_payment_reminder_status` hinzu. 1. Forderung mit `get_receivable` und der `sourceDraftId` der ausgestellten Originalrechnung lesen. Nur eine geeignete, eindeutig bekannte und überfällige offene Forderung kann gemahnt werden. `search_receivables` mit `review: "reminders"` grenzt die Prüfliste ein; ungeklärte Treffer sind zuerst in der App zu klären. 2. Vor einer neuen Anlage mit `search_payment_reminders`, `sourceDraftId` und `status: "draft"` nach einem vorhandenen Entwurf suchen und den passenden fortsetzen. Eine neue Zahlungserinnerung (`payment_reminder`) oder Mahnung (`dunning`) mit `expectedReceivableVersion` vorbereiten. Datum, Zahlungsfrist, Text und Layout sind bearbeitbar. Das Ausstellungsdatum darf nicht in der Zukunft liegen, die Frist muss danach liegen, der Text darf nicht leer sein. Ein fehlendes `layoutId` übernimmt bei Anlage das Original-Layout; bei Updates das gelesene Layout mitsenden. 3. Das PDF mit `preview_payment_reminder` zeigen. Vor `issue_payment_reminder` musst du die konkrete Fassung ausdrücklich bestätigen. Der Aufruf verwendet `expectedUpdatedAt`, `previewToken` und `confirmed: true`. 4. Eine ausgestellte Mahnung behält Nummer, PDF und Forderungssnapshot. Für den heutigen Zahlungsstand erneut `get_receivable` verwenden. Geänderte Zahlungen oder Druckdaten machen eine offene Vorschaufreigabe ungültig. Für die vollständige PDF-Vorschau `pdf.nextOffset` als nächsten `offset` und den gelieferten Hash als `expectedSHA256` an denselben Vorschauaufruf senden; ID und `expectedUpdatedAt` bleiben unverändert. Erst nach vollständigem Empfang Größe und SHA-256 prüfen und das PDF zeigen. Bei ausgestellten oder zurückgezogenen Mahnungen liefert die Vorschau das gespeicherte Original samt Snapshot und einen leeren `previewToken`; dies ist keine erneute Ausstellungsfreigabe. Mahnungen erzeugen keine neue Forderung, Buchungen, Gebühren, Zinsen oder Nachrichten. `change_payment_reminder_status` kann auf deinen Wunsch einen offenen Entwurf löschen, eine ausgestellte Mahnung zurückziehen oder einen bereits extern erfolgten Versand vermerken. Der Versandvermerk ist weder ein Versandauftrag noch ein Zustellnachweis. Die PDF-Vorschau und Downloads enthalten alle gedruckten Angaben. ## Rechnungskorrekturen `get_invoice_correction_capacity` liest die noch korrigierbaren Bruttobeträge der Positionen aus einer ausgestellten eigenen Rechnung. Offene Korrekturentwürfe reservieren keine Beträge. Nur ausgestellte Korrekturen mindern die Kapazität; ihre ausgestellte Aufhebung gibt sie wieder frei. Mit Schreibzugriff erstellen `create_invoice_correction` und `update_invoice_correction` einen quellgebundenen Korrekturentwurf. Übergeben werden Grund, Datum und **positive Bruttominderungen in EUR-Cent**, begrenzt durch den verbleibenden Betrag jeder Originalposition. Empfänger und historische Steuerbehandlung kommen aus dem Original. `layoutId` wählt `modern` oder `classic`; ohne Angabe wird bei Anlage das Original-Layout übernommen, bei Änderung das gespeicherte Layout beibehalten. Bei Anlage bezeichnet `id` den ursprünglichen Rechnungsentwurf und `expectedUpdatedAt` den Wert aus der Kapazitätsantwort. Bei Änderung bezeichnet `id` den Korrekturentwurf und die Version dessen gelesenen `updatedAt`. Der allgemeine Aufruf `update_sales_draft` ersetzt diese Korrekturwerkzeuge nicht. Falls `originalQuantity` und `unitCode` vorliegen, stammen sie aus dem ausgestellten E-Rechnungs-XML. Eine Mengenhilfe berechnet den proportionalen Bruttobetrag aus `originalGrossMinor × gewählte Menge ÷ originalQuantity`, auf Cent gerundet und durch `remainingGrossMinor` begrenzt. Sie beschreibt keinen Warenbestand und keine verbleibende Menge. Die Ausgabe erfolgt über die vorhandenen Werkzeuge `preview_sales_document` und nach deiner ausdrücklichen Bestätigung `finalize_sales_draft`. Dabei entstehen ein eigener unveränderlicher Beleg und entsprechende Buchungen. `prepare_correction_reversal` bereitet die vollständige Aufhebung einer ausgestellten Korrektur als neuen Entwurf vor; auch dieser wird separat angezeigt und bestätigt. Originalrechnung, zugeordnete Bankumsätze und bereits ausgestellte PDFs bleiben erhalten. Eine Rechnungskorrektur ist keine Gutschrift im Abrechnungsverfahren und führt keine Erstattung oder Nachricht aus. Vor der Bestätigung alle Seiten der aktuellen Vorschau zeigen. `finalize_sales_draft` erhält unverändert deren `previewToken`, `updatedAt` als `expectedUpdatedAt`, `grossTotal` als `expectedGrossTotal` und `buyerName` als `expectedBuyerName`. Das fertige PDF ist über `download_sales_document` mit der Korrekturentwurf-ID verfügbar. Rückzahlungen oder Verrechnungen sind ein eigener Vorgang, siehe [Erstattungen und Verrechnungen](#erstattungen-und-verrechnungen). ## Erstattungen und Verrechnungen ### Guthaben und Verrechnungsziele lesen `get_correction_settlement` erwartet in `id` die **Beleg-ID der ausgestellten Rechnungskorrektur**, nicht ihre Entwurf-ID. Das Ergebnis enthält die Rechnungsnummern, den Versionsdigest `revision`, den verfügbaren Betrag `refundAvailableMinor` in EUR-Cent und bisher dokumentierte Rückzahlungen oder Verrechnungen. Der Verlauf zeigt bis zu 50 Einträge; `paymentsTruncated` kennzeichnet weitere Einträge, die du in der App einsehen kannst. Zurückgenommene Erfassungen bleiben erkennbar. Der verfügbare Betrag ist sowohl durch den Rest dieser Korrektur als auch durch das gesamte Guthaben der Originalrechnung einschließlich aller Korrekturen und Zahlungen begrenzt. Eine Minderung einer noch unbezahlten Rechnung erzeugt deshalb nicht automatisch ein auszahlbares Guthaben. Unklare Zahlungszuordnungen sperren die Erfassung. Ein gesperrter Nullwert bestätigt keine erfolgte Erstattung. Für eine neue Erstattung oder Verrechnung müssen `disabledReason` leer und `refundAvailableMinor` ausreichend sein. Verwende nicht stattdessen `refundDueMinor` der Originalrechnung: Es beschreibt deren Gesamtanspruch, nicht den für diese Korrektur aktuell verfügbaren Betrag. `search_correction_settlement_targets` liefert bis zu 20 geeignete offene Ausgangsrechnungen desselben Kunden. Maßgeblich sind die gespeicherte Kontakt-ID, Kundennummer und das Personenkonto; ein ähnlicher Name reicht nicht. Bei `hasMore: true` die Suche nach Rechnungsnummer eingrenzen. Stornierte oder festgeschriebene Belege sowie unklare Zahlungsstände sind ausgeschlossen. Mit `targetDocumentId` prüft `get_correction_settlement` zusätzlich eine bestimmte Zielrechnung und liefert deren `revision` und `openMinor`. Lesen verändert keine Belege oder Buchungen. ### Eine Erstattung oder Verrechnung ausdrücklich erfassen `record_correction_settlement` gibt es nur mit Schreibzugriff. Vor jedem Aufruf müssen dir die konkrete Aktion, beide betroffenen Rechnungen bei einer Verrechnung, Betrag und Datum gezeigt werden. Erst nach deinem ausdrücklichen Auftrag darf `confirmed: true` gesetzt werden. | `action` | Bedeutung und benötigte Angaben | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `refund` | Eine von dir **bereits ausgeführte** Rückzahlung dokumentieren. Positiven Betrag `amountMinor`, tatsächliches `date` und `method: "cash"` oder `"clearing"` angeben. Keine Zielrechnung und keine `paymentId`. Ein bereits über einen importierten Bankumsatz zugeordneter Rückzahlungsbetrag darf nicht noch einmal erfasst werden. | | `offset` | Einen positiven Betrag `amountMinor` mit einer anderen geeigneten offenen Rechnung verrechnen. `targetDocumentId`, `expectedTargetRevision` und das vereinbarte Datum angeben. `method` und `paymentId` weglassen. Der Server erzeugt eine negative Zahlung am Korrekturbeleg und eine gleich hohe positive Zahlung an der Zielrechnung gemeinsam. | | `reverse` | Eine dokumentierte Erfassung durch Gegenbuchungen zurücknehmen. `paymentId` aus dem Verlauf und ein Datum ab dem ursprünglichen Zahlungsdatum angeben; `amountMinor`, `method` und `targetDocumentId` weglassen. Bei einer Verrechnung ist zusätzlich `expectedTargetRevision` erforderlich. Beide Seiten werden gemeinsam zurückgenommen. | Alle Aktionen brauchen `expectedRevision` aus dem zuvor gelesenen Korrekturguthaben und einen `idempotencyKey`. Vor einer Verrechnung oder deren Rücknahme auch die Zielrechnung mit `get_correction_settlement` prüfen und deren frische Revision unverändert mitsenden. Der Betrag einer Verrechnung darf weder das verfügbare Guthaben noch den offenen Zielbetrag überschreiten. Für eine Rücknahme die ursprüngliche `targetDocumentId` aus dem Zahlungsverlauf lesen, auch wenn diese Rechnung inzwischen ausgeglichen ist und deshalb nicht mehr in der Zielsuche erscheint. Diese ID wird nur zum Lesen der aktuellen Zielrevision verwendet; im `reverse`-Schreibaufruf bleibt `targetDocumentId` leer. Eine Rücknahme hebt die dokumentierte Zahlung oder Verrechnung auf, nicht die Rechnungskorrektur selbst; dafür ist der gesonderte Ablauf mit `prepare_correction_reversal` zuständig. Die Rücknahme ergänzt Gegenbuchungen. Ursprüngliche Einträge bleiben auch bei Festschreibung erhalten; ein Verrechnungspaar kann nicht einseitig zurückgenommen werden. Ein unbekannter Zahlungsstand sperrt auch die Rücknahme. Diese Aktionen erfassen Zahlungs- oder Gegenbuchungen. Sie veranlassen **keine Überweisung**, erzeugen keinen künstlichen Bankumsatz, ändern keine Umsatz- oder Steuerbeträge der ausgestellten Korrektur und verschicken keine Nachricht. Dokumentierte Rückzahlung und tatsächlicher Bankauftrag sind getrennte Vorgänge. Eine Verrechnung oder Erstattung sperrt das Aufheben einer Bankzuordnung mit `delete_match` nicht, anders als eine manuell erfasste Zahlung (Kasse oder Verrechnungskonto); der über die Bank gezahlte Betrag ist danach wieder offen. ## Wiederkehrende Rechnungsentwürfe Mit Lesefreigabe zeigen `list_recurring_invoices`, `get_recurring_invoice` und `get_recurring_invoice_dates` Serienvorlagen, die nächsten Kalendertermine und die letzten 50 vorbereiteten Perioden. Ist ein Inhalt gekürzt oder nicht unverändert übertragbar (`editable: false`), bearbeitest du die Vorlage in der App. Mit Schreibzugriff stehen zusätzlich zur Verfügung: * `create_recurring_invoice`, `update_recurring_invoice`: Vorlage mit Rechnungsinhalt, Kalenderplan und Zahlungsfrist anlegen oder ändern. Ohne ausdrücklich bestätigtes `activate: true` wird pausiert; eine Änderung widerruft die bisherige Automationsfreigabe. * `activate_recurring_invoice`: die aktuelle Vorlage auf deinen ausdrücklichen Wunsch zur automatischen Vorbereitung fälliger Entwürfe freigeben. Die Freigabe hängt an deiner Mitgliedschaft in der Firma, nicht an der MCP-Verbindung: Trennst du die Verbindung, läuft die Serie weiter; stoppen lässt sie sich mit Pausieren oder Beenden. * `pause_recurring_invoice`, `end_recurring_invoice`: automatische Vorbereitung pausieren oder die Vorlage endgültig beenden. Bestehende Entwürfe und Rechnungen bleiben erhalten. * `prepare_recurring_invoice_period`: genau einen Entwurf für einen ausdrücklich gewählten gültigen Kalendertermin vorbereiten, auch für eine künftige Periode oder eine pausierte Vorlage. Es gibt einen wöchentlichen oder monatlichen Kalenderplan. Ein Monatsanker 31 fällt in kurzen Monaten auf deren letzten Tag und anschließend wieder auf den 31. Ohne Startdatum beginnt eine neue Vorlage am Folgetag; es gibt keine automatische rückwirkende Erzeugung. Pro Vorlage und Periode entsteht höchstens ein Entwurf, unabhängig von Änderungen und Wiederholungsschlüsseln. Wurde dieser Entwurf gelöscht, wird er nicht erneut erzeugt. Die **über MCP freigegebenen Serien** vergeben keine endgültigen Rechnungsnummern und buchen nicht. Ihre Prüfung und Ausstellung bleibt ein eigener Schritt am erzeugten Rechnungsentwurf. Web und API können außerdem Serien mit automatischer Ausstellung freigeben; MCP kann solche Vorlagen lesen, pausieren oder beenden, aber weder ändern noch aktivieren oder Perioden daraus erzeugen. Die Vorlage nennt ihren `generationMode` und bei `editable: false` einen `editableReason`; diese Sperre ist verbindlich. Am einzelnen Lauf enthält die MCP-Antwort weder Modus noch `documentId`: Aus einem aufgeführten `draftId` darf deshalb nicht auf einen noch offenen Entwurf geschlossen werden; den aktuellen Zustand mit `get_sales_document` lesen. Kein Modus versendet Nachrichten. Ein Serienkalender ist keine Vorschau: `prepare_recurring_invoice_period` legt tatsächlich einen Entwurf an und verbraucht diesen Termin. Er darf nicht nur zum Anzeigen eines Beispiels aufgerufen werden. Das Serienlayout lässt sich mit dieser MCP-Fassung nicht auswählen; die App bietet dafür die Layoutauswahl an. ## Beträge und Darstellungen Forderungsstände und Korrekturminderungen mit dem Suffix `Minor` sind ganze EUR-Cent, beispielsweise `2380` für 23,80 €. Die Rechnungspositionen einer Serienvorlage verwenden dagegen `unitPrice` als EUR-Dezimalzeichenfolge, etwa `"20.00"`, zusammen mit `priceType: "net"` oder `"gross"`. Auch `grossTotal` und `expectedGrossTotal` der Vertriebsdokument-Vorschau sind EUR-Dezimalzeichenfolgen. Diese Einheiten dürfen nicht vermischt werden. Eine Netto- oder Mengenhilfe ersetzt nicht die positiven Bruttocentbeträge des Korrekturauftrags; die endgültige Steuer- und Centaufteilung berechnet bimetrics aus dem Original. Layoutänderungen betreffen das jeweilige Dokument, nicht den Firmenstandard. Für einen geänderten Entwurf ist eine neue Vorschau nötig; bereits ausgestellte PDFs werden nicht neu gestaltet. ## Wiederholungen und Versionsschutz Schreibaufrufe benötigen einen stabilen `idempotencyKey`; denselben Schlüssel ausschließlich mit identischem Inhalt wiederholen. Änderungen und Statusaktionen verwenden den exakt gelesenen Versionswert. Bei einem Konflikt neu lesen und mit dir prüfen, ohne die Version stillschweigend zu ersetzen. Änderungen an Zahlungen, Zuordnungen oder Korrekturen können eine gelesene Revision ungültig machen. Ein ausgewiesenes Guthaben des Kunden ist noch keine ausgeführte Zahlung.