Tool-Übersicht, Fassung 2026-10-11

Diese Fassung ergänzt die Werkzeuge vom 10.10.2026. Es gilt weiterhin das Rechtspaket 2026-10-09-v1. 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 MahnungenLink zu diesem Abschnitt kopieren

Eine Lesefreigabe umfasst diese zusätzlichen Werkzeuge:

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.

RechnungskorrekturenLink zu diesem Abschnitt kopieren

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 VerrechnungenLink zu diesem Abschnitt kopieren

Guthaben und Verrechnungsziele lesenLink zu diesem Abschnitt kopieren

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 erfassenLink zu diesem Abschnitt kopieren

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.

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ürfeLink zu diesem Abschnitt kopieren

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 DarstellungenLink zu diesem Abschnitt kopieren

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 VersionsschutzLink zu diesem Abschnitt kopieren

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.