Tool-Referenz

apiVersion v1 · schemaRevision 2 · 68 tools

Jeder Tool-Aufruf kann außerdem einen dieser Transport-Codes zurückgeben, hier nur einmal aufgeführt: UNAUTHORIZED, FORBIDDEN_SCOPE, VALIDATION_ERROR, RATE_LIMITED, INTERNAL_ERROR

Lesen

• mcp_health

  Verbindungs- und Einrichtungsprobe: prüft das Partner-Token und die Verarbeitungskette von Anfang bis Ende und meldet unter setup, welche Voraussetzungen für einen echten Versand erfüllt sind (Absender-Profil, AVV, Guthaben, Sandbox, Freigabe, Marke, Briefpapier, Vorlagen) und welcher Schritt als nächster ansteht. Bei einem neuen Konto listet setup.goldenPath die Einrichtungsschritte in Reihenfolge. Jeder Schritt trägt humanSummary (de, en), einen Satz in Alltagssprache für den Menschen; Tool-Namen, nextTool, fixUrl und messageDe/messageEn sind maschinenlesbar. checkRender: true prüft zusätzlich, ob das Rendern gerade funktioniert (Vorschau, Thumbnail), etwa vor dem Bau einer Vorlage, die danach als Bild geprüft wird. Die Antwort kommt in etwa 3 Sekunden: eine Prüfung über ihrem Zeitbudget steht unter degraded und meldet ihren vorsichtigen Standardwert.

  Feld	Typ
  checkRender	boolean	Optional	Prüft zusätzlich den Render-Pfad (Composer + Rasterizer). Standard false.

• profile_getScope: profile:read

  Liefert das Partnerprofil im Überblick: Standard-Absenderadresse, hinterlegte Signatur und Briefkopf, gespeicherte Presets, eine kurze Wallet-Zusammenfassung und das aktuelle Preismodell des Partners (Standardpreis oder Mengenstaffel, inklusive nächster Staffelstufe).

  Keine Eingabefelder außer reasoning.

• wallet_balanceScope: wallet:read

  Liefert den aktuellen Wallet-Stand: Guthaben, den für wartende Briefe reservierten Betrag, das verfügbare Guthaben, Tageslimit für Briefe und Kosten, den nächsten Reset-Zeitpunkt sowie das aktuelle Preismodell (Standardpreis oder Mengenstaffel). Bleibt das verfügbare Guthaben unter den geplanten Versandkosten, liefert wallet_topup_link den Link zum Aufladen.

  Keine Eingabefelder außer reasoning.

• sender_profile_listScope: sender_profile:read

  Listet alle Absenderprofile des Partners mit ihrer Rechtsform und ob die Pflichtangaben vollständig sind.

  Keine Eingabefelder außer reasoning.

• sender_profile_getScope: sender_profile:read

  Liefert ein einzelnes Absenderprofil mit allen Pflichtangaben, Bankverbindung und Disclaimer. profileId ist optional und steht sonst für das Standardprofil.

  Feld	Typ
  profileId	string (uuid)	Optional	Optional, Standard ist das Standardprofil.

  Fehlercodes: NOT_FOUND

• mandant_getScope: mandant:read

  Liefert einen Mandanten mit Adressen, Kategorie, Sachbearbeiter, Monatslimit, verbrauchtem Monatsbudget, Aufbewahrungsdauer und der Briefanzahl der letzten 12 Monate.

  Feld	Typ
  mandantId	string	Optional
  mandantennummer	string	Optional

  Fehlercodes: NOT_FOUND

• mandant_listScope: mandant:read

  Listet die Mandanten des Partners, optional gefiltert nach Suchbegriff, Kategorie oder Tag.

  Feld	Typ
  searchQuery	string	Optional
  kategorieFilter	string	Optional
  tagFilter	string	Optional
  since	string (date-time)	Optional	Nur Mandanten, die seit diesem Zeitpunkt angelegt wurden (ISO 8601).
  limit	integer	Optional	Standard 20, maximal 100.
  offset	integer	Optional	Versatz für die Seitennavigation. Standard 0.

• mandant_searchScope: mandant:read

  Sucht Mandanten über Mandantennummer, Name, Tags oder Sachbearbeiter und nennt für jeden Treffer die passende Spalte. Nächster Schritt mit der gefundenen mandantennummer: document_create erzeugt daraus eine Rechnung, Mahnung, Zahlungserinnerung oder Gutschrift, mandant_get liefert die vollständigen Stammdaten, letter_create_draft schreibt einen normalen Brief.

  Feld	Typ
  query	string	Pflicht
  since	string (date-time)	Optional	Nur Mandanten, die seit diesem Zeitpunkt angelegt wurden (ISO 8601).
  limit	integer	Optional	Standard 20, maximal 100.
  offset	integer	Optional	Versatz für die Seitennavigation. Standard 0.

• template_listScope: template:read

  Listet die Brief-Vorlagen (Vorlagenliste, template list) für Anlässe wie Kündigung, Rechnung, Mahnung, Angebot, Vertrag und Behördenpost, mit Kategorie, Version und Platzhaltern (Merge-Feldern). Der technische Tool-Name ist template_list. Standardmäßig kommen die freigegebenen Vorlagen; statusFilter mit dem Scope template:write liefert auch offene Entwürfe. Jeder Eintrag sagt mit curated: true, ob es eine kuratierte FrankKi-Standardvorlage ist (die Bibliothek zum Kopieren), und mit hasBlocks: true, ob sie ein strukturiertes Layout mit Tabellen und Summen trägt statt Fließtext. Nächster Schritt: template_get liefert eine Vorlage vollständig (bei einer Blockvorlage inklusive blocksTemplate und styleDefs zum Kopieren und Anpassen), template_apply_with_merge_fields füllt sie mit Werten.

  Feld	Typ
  query	string	Optional	Suchwort für Name und Kategorie, z. B. Mahnung oder Miete.
  kategorieFilter	string	Optional
  statusFilter	released | draft | all	Optional	released (Standard) zeigt alle freigegebenen Vorlagen. Eigenständige Formularvorlagen tragen sendable:false und brauchen beim Anwenden ein Anschreiben. draft zeigt nur offene Entwürfe, all beide. draft und all brauchen zusätzlich den Scope template:write.
  source	own | library | all	Optional	own liefert die Vorlagen des Kontos, library die FrankKi-Bibliothek, all (Standard) beide, die eigenen zuerst. Jede Zeile nennt ihre Herkunft in source.
  limit	integer	Optional	Standard 50, maximal 100.
  offset	integer	Optional	Versatz für die Seitennavigation. Standard 0.

• template_getScope: template:read

  Liefert eine einzelne Vorlage mit Betreff- und Inhaltsvorlage, den Merge-Feldern und der empfohlenen Freigabe-Voreinstellung. Eine Blockvorlage liefert zusätzlich blocksTemplate und styleDefs; kopiert und angepasst speichert template_save sie als eigenen Entwurf. Die Gestaltungskette beginnt hier: template_get auf einer kuratierten Standardvorlage (template_list markiert sie mit curated: true), Änderungen an blocksTemplate, letter_preview rendert den Stand, template_save speichert ihn, template_preview zeigt die gespeicherte Version, template_release gibt sie frei. Mit versionId und dem Scope template:write lässt sich auch eine bestimmte Entwurfsversion lesen. Nächster Schritt: template_apply_with_merge_fields füllt die Platzhalter mit Werten.

  Feld	Typ
  templateId	string (uuid)	Pflicht
  versionId	string (uuid)	Optional	Optional: eine bestimmte Version, auch ein Entwurf. Braucht zusätzlich den Scope template:write. Ohne Angabe kommt die freigegebene Version.

  Fehlercodes: NOT_FOUND

• letter_getScope: letter:read

  Liefert einen Brief des Partners samt zugehörigem Auftrag und einer 24 Stunden gültigen Download-URL für die PDF. status ist der Briefstatus; vor dem Auftrag trägt ein Brief in der Freigabe denselben Status wie in order_status: pending_approval, approved_in_grace oder queued_autopilot, dazu approval mit approvalId. letterStatus ist der gespeicherte Briefstatus.

  Feld	Typ
  letterId	string (uuid)	Optional
  orderId	string (uuid)	Optional

• letter_listScope: letter:read

  Listet die Briefe des Partners mit optionalen Filtern nach Empfängername, Betreff, Status und Zeitpunkt. status ist der Briefstatus; vor dem Auftrag trägt ein Brief in der Freigabe denselben Status wie in order_status: pending_approval, approved_in_grace oder queued_autopilot, dazu approval mit approvalId. letterStatus ist der gespeicherte Briefstatus.

  Feld	Typ
  recipientNameContains	string	Optional
  subjectContains	string	Optional
  statusFilter	draft | ready | ordered | printed | shipped | delivered | pending_approval | sent | unsent	Optional	Briefstatus draft, ready, ordered, printed, shipped oder delivered. pending_approval steht für Briefe, die auf eine Freigabe warten; draft und ready enthalten die übrigen Briefe dieses Stands. sent steht für alle Briefe mit einem angenommenen Auftrag, unsent für alle übrigen.
  since	string (date-time)	Optional
  limit	integer	Optional
  offset	integer	Optional

• sender_profile_validateScope: sender_profile:read

  Prüft, ob ein Absenderprofil (per profileId) oder ein vorgeschlagener Feldsatz alle Pflichtangaben für seine Rechtsform enthält. Der Aufruf nimmt genau eine Form: profileId ODER rechtsform + proposedFields. proposedFields ist ein Objekt; ein JSON-kodierter Objekt-String wird ebenfalls akzeptiert. Liefert valid, missingFields und weiche Hinweise. Meldet eine Lücke als Ergebnis und läuft dabei durch.

  Keine Eingabefelder außer reasoning.

• analytics_summaryScope: analytics:read

  Liefert die aggregierten Kennzahlen des Partnerkontos: Briefe pro Monat, Kosten pro Mandant zur Weiterberechnung, Laufzeiten bis zur Zustellung, Fehlerquoten und Ausgaben gegen die gesetzten Limits. Beträge sind Netto-Kosten in Cent.

  Feld	Typ
  metric	overview | letters_per_month | cost_per_mandant | delivery_times | failure_rates | spend_vs_caps	Optional	Welche Auswertung. overview (Standard) fasst die letzten drei Monate zusammen.
  months	integer	Optional	Trendlänge für letters_per_month und failure_rates, 1 bis 24, Standard 12.
  since	string	Optional	Zeitraumbeginn für cost_per_mandant und delivery_times, zum Beispiel 2026-01-01. Standard: letzte 90 Tage.
  until	string	Optional	Zeitraumende, Standard jetzt.
  topN	integer	Optional	Anzahl Mandanten in cost_per_mandant, 1 bis 50, Standard 10.

• address_listScope: address:read

  Listet die Adressen im Partner-Adressbuch. Optional nach Name, Stadt oder Mandant gefiltert.

  Feld	Typ
  searchQuery	string	Optional
  limit	integer	Optional
  offset	integer	Optional	Versatz für die Seitennavigation. Standard 0.

• address_validateScope: address:read

  Prüft eine Adresse anhand landesspezifischer Regeln und liefert valid (dasselbe Urteil wie die Adressprüfung von order_send) sowie je Feld, was fehlt, falsch geformt ist oder vom Ort abweicht. Nur eine Prüfung, das Adressbuch bleibt unverändert; Anlegen und Ändern übernimmt address_upsert.

  Feld	Typ
  name	string	Pflicht
  company	string	Optional
  street	string	Pflicht
  houseNumber	string	Optional
  pobox	string	Optional
  zip	string	Optional
  city	string	Pflicht
  country	string	Optional	ISO-3166-alpha-2, default DE.
  mandantennummer	string	Optional
  addressType	recipient | sender | billing	Optional
  isDefault	boolean	Optional

• template_apply_with_merge_fieldsScope: template:read

  Füllt die Platzhalter einer gespeicherten Vorlage mit Werten und gibt Betreff und Inhalt oder ein vollständiges Anschreiben-Formular-Paket zurück. Bei einer Blockvorlage kommen statt content die fertigen blocks zurück. Briefkopf und Marke werden getrennt bei Vorschau oder Versand gewählt. Eine eigenständige Formularvorlage mit sendable:false und releaseBlocker:null braucht coverTemplateId aus einer direkt adressierbaren Briefvorlage; eine gespeicherte Verknüpfung bleibt nur der optionale Standard. order_send versendet das Ergebnis mit templateId, templateVersionId, coverTemplateId, coverTemplateVersionId und den ursprünglichen templateMergeValues und rendert damit genau diese Version neu. order_send erwartet die Paketabschnitte in der Form, in der sie hier zurückkommen. Fehlt eine Pflichtangabe, antwortet das Tool mit MERGE_FIELDS_MISSING und nennt die fehlenden oder ungültigen Felder.

  Feld	Typ
  templateId	string (uuid)	Pflicht	Id der Vorlage aus template_list / template_get.
  templateVersionId	string (uuid)	Optional	Exakte freigegebene oder ersetzte Vorlagenversion. Ohne Angabe wird die aktuell freigegebene Version verwendet.
  coverTemplateId	string (uuid)	Optional	Optionales Anschreiben für eine eigenständige Formularvorlage. Ohne gespeicherte Verknüpfung ist es zum Anwenden erforderlich.
  coverTemplateVersionId	string (uuid)	Optional	Optional: exakte freigegebene Version des gewählten Anschreibens.
  mergeValues	Objekt	Optional	Zuordnung von Platzhalter-Namen zu Werten, z. B. { "provider": "Telekom" }. Der Typ des Merge-Feldes gilt: date erwartet ISO JJJJ-MM-TT, currency ganzzahlige Cent, number eine Zahl, rows eine Liste von Zeilenobjekten mit den Spaltenschlüsseln der gebundenen Tabelle.
  language	de | en	Optional	Sprache für die Formatierung von Betrag und Datum. Standard de.
  mandantennummer	string	Optional	Optionaler Mandantenbezug (nur Kontext).

  Fehlercodes: NOT_FOUND

• shipping_quoteScope: letter:read

  Ermittelt Preis, Briefformat, Versandart und voraussichtliche Laufzeit für einen geplanten Brief, bevor er versendet wird. Die Schätzung braucht nur Seitenzahl, Land und Versandart. Steht der Brief schon fest, versendet ihn order_send, und order_send mit dryRun:true liefert den genaueren Preis für genau diesen Brief. Der Preis gilt pro Brief und enthält bereits die Mengenstaffel des Partners, falls eine greift (Feld tierId); die Staffelpreise selbst liefert pricing_tiers. Ob es Einschreiben gibt, richtet sich nach dem aktuellen Katalog des Ziellands. einschreiben_einwurf und einschreiben_uebergabe sind deutsche Produkte; die Schweiz hat ch_einschreiben. Für andere Ziele listet ein Standard-shipping_quote für das Land die verfügbaren Versandarten in availableDeliveryTypes, und ein Quote für den gewählten Code liefert dessen Preis. Eine abgelehnte Kombination aus Land und Versandart gilt für genau dieses Paar, ein Katalogstand für genau diesen Stand. Sendungsverfolgung und Einschreiben sind verschiedene Produkte.

  Feld	Typ
  pageCount	integer	Pflicht	Seitenzahl für eine allgemeine Schätzung. Mit letterId verwendet FrankKi die gespeicherte Seitenzahl und ignoriert diesen Wert.
  color	boolean	Optional	Farbe für eine Schätzung. Ohne Angabe gilt die Farbe des Standard-Briefpapiers. Mit letterId liest FrankKi die Farbe aus der gespeicherten Vorschau.
  deliveryType	standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered	Pflicht	Versandart-Code. Einschreiben: einschreiben_einwurf und einschreiben_uebergabe für Deutschland, ch_einschreiben für die Schweiz; für andere Länder nennt ein Standard-Quote die Codes in availableDeliveryTypes.
  express	boolean	Optional
  country	string, max. 2 Zeichen	Optional	ISO 3166-1 alpha-2, Standard DE.
  letterId	string (uuid)	Optional	Optional: die letterId eines bestehenden Entwurfs. Dann kommen Seitenzahl und Farbe aus der gespeicherten Vorschau; den endgültigen Preis inklusive Anhängen liefert order_send mit dryRun:true.

• pricing_tiersScope: letter:read

  Liefert die Staffelpreise (Mengenrabatte) von FrankKi: ab welcher Monatsmenge welcher Beispielpreis pro Brief gilt. Das beantwortet Fragen nach Mengenrabatt, Volumenpreis, Staffelpreis oder Großkundenpreis. Die Beispielpreise gelten für einen einseitigen Standardbrief in Schwarzweiß innerhalb Deutschlands, der echte Preis pro Brief hängt zusätzlich von Seitenzahl, Farbe, Versandart und Zielland ab (den liefert shipping_quote).

  Keine Eingabefelder außer reasoning.

• order_statusScope: order:read

  Liefert den Stand eines Briefs: Status, deutsche Sendungsverfolgung, Sendungsnummer (bei Einschreiben), voraussichtliche Zustellung und ob er sich noch stornieren lässt. Der Aufruf nimmt genau eine Kennung: orderId, approvalId (aus order_send, solange orderId null ist) oder letterId. Vor dem Versand kommt status queued_autopilot mit dispatchAt, humanSummary (de, en) und cancelWith. Bei awaiting_partner_fix wartet der Brief auf order_fix_resubmit, bei failed nennt failure den Grund und nextStep den Weg zurück. Solange cancellable true ist, stoppt order_cancel den Versand.

  Feld	Typ
  orderId	string (uuid)	Optional
  approvalId	string (uuid)	Optional	Aus order_send, solange orderId null ist.
  letterId	string (uuid)	Optional

  Fehlercodes: NOT_FOUND

• order_einlieferungsbelegScope: order:read

  Liefert den Einlieferungsbeleg (Einlieferungsnachweis) zu einem versendeten Auftrag, sobald der Brief eingeliefert ist und der Versanddienstleister einen Beleg ausstellt: eine 7 Tage gültige Download-URL für den Beleg (eine PDF, wenn der Versanddienstleister eine ausstellt, sonst ein JSON-Nachweis aus seinen Statusdaten; belegFormat nennt das Format, ein neuer Aufruf liefert einen frischen Link), den Poststempel, den Versanddienstleister sowie den geprüften Nachweis aus dem GoBD-Archiv. Der Beleg zeigt die Einlieferung bei der Post. Sendungsnummer und Zustellstatus eines Einschreibens liefert order_status.

  Feld	Typ
  orderId	string (uuid)	Pflicht

  Fehlercodes: NOT_FOUND

• approval_listScope: approval:read

  Listet die Freigaben des Kontos, neueste zuerst, mit einer zeitlich begrenzten PDF-Vorschau, den Kosten, dem Grund und den Fristen. Standardmäßig die offenen Freigaben und die freigegebenen Briefe, die noch in ihrem Stornofenster warten (Autopilot, Chat); graceState nennt dispatchAt. status all zeigt alles. approval_decide entscheidet über eine der zurückgegebenen approvalIds.

  Feld	Typ
  status	pending | approved | rejected | expired | all	Optional	Standard: offen plus Stornofenster.
  since	string (date-time)	Optional	Nur Freigaben, die seit diesem Zeitpunkt eingereicht wurden (ISO 8601).
  approvalId	string	Optional	Eine einzelne Freigabe mit allen Angaben: alle Diff-Segmente der Vorlage und alle Empfänger eines Stapels. Ohne approvalId kürzt die Liste beides.
  limit	integer	Optional	Standard 20, maximal 100.
  offset	integer	Optional	Versatz für die Seitennavigation. Standard 0.

• setup_fix_linkScope: profile:read

  Gibt einen Punkt an den Menschen im Browser weiter: Guthaben aufladen, den Auftragsverarbeitungsvertrag (AVV) unterschreiben oder das Absender-Profil vervollständigen. Liefert die passende Seite und eine Karte, die den Briefentwurf sichtbar stehen lässt und selbst merkt, wenn der Mensch zurück ist. Bezahlt wird im Browser.

  Feld	Typ
  gap	wallet | avv | senderProfile	Pflicht	Welcher Punkt übergeben wird: wallet (Guthaben), avv (Auftragsverarbeitungsvertrag) oder senderProfile (Absender-Profil).

• wallet_topup_linkScope: wallet:read

  Erstellt einen Stripe-Checkout-Link zum Aufladen des Wallet-Guthabens. Die Kartendaten bleiben bei Stripe; das Guthaben wird nach Abschluss der Zahlung gutgeschrieben.

  Feld	Typ
  amountEuros	number	Pflicht	Aufladebetrag in Euro, zwischen 10 und 500.
  requestNonce	string, max. 200 Zeichen	Optional	Optionaler stabiler Wiederholungs-Schlüssel. Bei einer Wiederholung denselben Wert senden, um denselben Checkout-Link zu erhalten statt eines zweiten.

  Fehlercodes: INSUFFICIENT_FUNDS

• template_diff_checkScope: template:read

  Vergleicht einen fertigen Brief mit seiner Vorlage und zeigt, wo er abweicht. Eine Blockvorlage vergleicht finalBlocks an Stelle von finalContent, Text für Text in Lesereihenfolge. Kostenlos und rein lesend.

  Feld	Typ
  templateId	string (uuid)	Pflicht	Id der Vorlage aus template_list / template_get.
  versionId	string (uuid)	Optional	Optional: bestimmte Version, sonst die freigegebene.
  finalSubject	string	Pflicht	Der finale Betreff des Briefs.
  finalContent	string	Optional	Der finale Brieftext. Ein Blockbrief kommt als finalBlocks.
  finalBlocks	Array<Objekt>	Optional	Die finalen Blöcke, wenn der Brief strukturiert ist. Verglichen werden die Texte in Lesereihenfolge.
  mergeFields	Objekt	Optional	Zuordnung der Platzhalter-Namen zu Werten, z. B. { "provider": "Telekom" }.

  Fehlercodes: NOT_FOUND

• letter_design_listScope: letter_design:write

  Listet die gespeicherten Briefpapiere (Briefdesigns) des Partners mit Name, ID und Hashes; mit designId liefert es ein Design samt vollständigem Design-JSON. Ein Design wird per Name oder ID beim Versand referenziert und trägt jede Post: Kündigung, Rechnung, Mahnung, Angebot, Vertrag und Behördenpost.

  Feld	Typ
  includeArchived	boolean	Optional	true schließt archivierte (gelöschte) Designs ein. Standard false.
  designId	string (uuid)	Optional	Ein einzelnes Briefdesign samt vollständigem Design-JSON. Ohne designId nennt die Liste je Design Name, ID und Hashes, ohne das Design-JSON.

• letter_design_previewScope: letter_design:write

  Rendert ein gespeichertes oder inline übergebenes Briefdesign (schemaVersion 1 oder 2) mit demselben Composer wie ein echter Versand, mit echten Absenderdaten, erfundenem Empfänger und Beispieltext. Liefert eine Inline-PNG-Seite, Seite 2 nur für continuationHeader, mit pages 0 nur Links. sampleVariant empty zeigt das Briefpapier allein, wie im Dashboard. Das zeigt vorab Kündigung, Rechnung, Mahnung, Angebot, Vertrag und Behördenpost auf diesem Briefpapier. Kostenfrei, der Brief bleibt ein Entwurf.

  Feld	Typ
  designId	string (uuid)	Optional
  design	unbekannt	Optional
  reference	Objekt	Optional
  sampleSubject	string, max. 200 Zeichen	Optional
  sampleContent	string, max. 4000 Zeichen	Optional
  sampleVariant	typical | empty	Optional	typical zeigt eine volle Beispielseite, empty das Briefpapier allein mit freier Textfläche. sampleContent geht vor.
  pages	integer	Optional	Standard 1, Seite 2 nur mit continuationHeader, 0 nur Links.
  resolution	thumb | full	Optional

  Fehlercodes: DESIGN_NOT_FOUND, DESIGN_RENDER_FAILED, DESIGN_ZONE_VIOLATION

• letter_design_list_presetsScope: letter_design:write

  Liefert die vom Inhaber freigegebenen native-v2 Briefpapiere als sichere Ausgangspunkte für Kündigung, Rechnung, Mahnung, Angebot, Vertrag und Behördenpost. Sie wächst mit jeder abgenommenen Vorlage. Die normale Liste nennt je Vorlage ID, Name, Beschreibung und Schlagwörter; mit presetId kommen das vollständige Design und genau eine echte Composer-Vorschau samt Inline-PNG.

  Feld	Typ
  presetId	string	Optional	Optional: lädt genau eine Vorlage samt gerenderter Vorschau. Ohne presetId bleibt die Liste bildfrei und günstig.
  pages	integer	Optional
  resolution	thumb | full	Optional

• brand_kit_getScope: profile:read

  Liest die gespeicherten Markenwerte für das nutzerseitige Ergebnis Briefkopf & Marke. Liefert Logo-Referenzen, Farben und Schrift für die weitere Gestaltung mit letter_design_preview und letter_design_save. Technischer Tool-Name: brand_kit_get.

  Keine Eingabefelder außer reasoning.

• signature_listScope: profile:read

  Listet die im Partnerprofil gespeicherten Unterschriften mit einer kurzlebigen Vorschau-URL (24 Stunden gültig).

  Keine Eingabefelder außer reasoning.

• letterhead_listScope: profile:read

  Listet die im Partnerprofil gespeicherten Briefköpfe mit einer kurzlebigen Vorschau-URL (24 Stunden gültig).

  Keine Eingabefelder außer reasoning.

• schedule_listScope: letter:schedule

  Listet die geplanten Sendungen des Partners mit Termin, Status und reservierter Summe.

  Feld	Typ
  statusFilter	scheduled | sent | cancelled | failed	Optional	Nur Planungen mit diesem Status.

• address_search_companyScope: address:read

  Sucht Firmen und Behörden im Verzeichnis und liefert die passende Versandadresse inklusive Behörden-Postfach.

  Feld	Typ
  query	string	Pflicht
  country	string	Optional

• letter_searchScope: letter:read

  Durchsucht die Briefe des Partners per Freitext über Betreff, Empfängername und Briefinhalt. status ist der Briefstatus; vor dem Auftrag trägt ein Brief in der Freigabe denselben Status wie in order_status: pending_approval, approved_in_grace oder queued_autopilot, dazu approval mit approvalId. letterStatus ist der gespeicherte Briefstatus.

  Feld	Typ
  query	string	Pflicht
  since	string (date-time)	Optional	Nur Briefe, die seit diesem Zeitpunkt geändert wurden (ISO 8601).
  limit	integer	Optional	Standard 20, maximal 100.
  offset	integer	Optional	Versatz für die Seitennavigation. Standard 0.

• archive_exportScope: archive:read

  Plant einen Archiv-Export (GoBD-CSV, DATEV, PDF-Bundle oder Mandanten-Allokation) für einen Zeitraum ein und liefert eine Job-ID zur Statusabfrage.

  Feld	Typ
  since	string (date-time)	Pflicht
  until	string (date-time)	Pflicht
  format	gobd_csv | datev_export | pdf_bundle | mandant_allocation_pdf | mandant_allocation_csv	Pflicht
  target	string	Optional
  mandantennummerFilter	string	Optional
  senderProfileFilter	string (uuid)	Optional
  notifyEmail	string (email)	Optional

  Fehlercodes: NOT_FOUND

• archive_export_statusScope: archive:read

  Liefert den Status eines Archiv-Export-Jobs und bei Fertigstellung eine 90 Tage gültige Download-URL.

  Feld	Typ
  jobId	string (uuid)	Pflicht

  Fehlercodes: NOT_FOUND

• letter_previewScope: order:send

  Rendert einen Brief, Entwurf oder ein Formular als Bild, so wie ein echter Versand ihn komponiert, und liefert Inline-PNGs, PDF-Link, Seitenzahl, Preis und designRender mit dem tatsächlichen documentMode, den gezeichneten Brief-Elementen und bodyStartMm. Die Vorschau ist kostenfrei, und der Brief bleibt liegen. Der Brief kommt über letterId, über eine freigegebene Vorlage (templateId, templateVersionId, templateMergeValues) oder inline mit content ODER blocks; der Empfänger über recipientAddressId oder die recipient-Felder. Bei letterId ist die eingebettete Karte die Vorschau für den Menschen; PDF-Link und Brieftext stehen zusätzlich im Ergebnis, für reine Textansichten. Ein ungespeichertes design gilt nur für diese eine Vorschau. Eigenständige Formulare (Selbstauskunft, Fragebogen, Zertifikat) rendern mit design: { "schemaVersion": 1, "documentMode": "form" } als Formular: dann entfallen Empfängerblock, Datum und Betreff, und der Inhalt beginnt bei 27 mm. Kompaktes blocks-Beispiel: {"blocks":[{"type":"heading","text":"Rechnung"},{"type":"table","columns":[{"key":"text","label":"Artikel","width":"grow"},{"key":"sum","label":"Summe","align":"right","format":"eur"}],"rows":[{"text":"Beratung","sum":32000}]},{"type":"totals","lines":[{"label":"Gesamt","amountCents":32000,"emphasis":true}]}]} Schema-Referenz: frankki://blocks-guide. Beim Nachbau eines Originals zeigen die PNGs Seite für Seite, ob Seitenzahl und wesentliche Geometrie passen; geänderte blocks oder ein geändertes design rendern im nächsten letter_preview-Aufruf neu. Das passende Layout speichert template_save als Entwurf, template_release gibt es frei.

  Feld	Typ
  letterId	string (uuid)	Optional	Gespeicherter Entwurf für die Vorschau. Alternativ kommt der Brief inline.
  subject	string, max. 200 Zeichen	Optional	Betreff. Ohne letterId erforderlich.
  content	string, max. 30000 Zeichen	Optional	Brieftext als Fließtext. Genau eines von content und blocks.
  blocks	Array<unbekannt> (min 1, max 200)	Optional	Strukturierter Briefinhalt als typisierte Blöcke, an Stelle von content. Limits: 200 Blöcke, 100 Zeilen/Tabelle, 20 Spalten, 2000 Zeichen/Zelle, 10 Bilder, 262144 Bytes.
  styleDefs	Objekt	Optional	Benannte Stile für das ganze Dokument (max. 24). Blöcke referenzieren sie über style.
  language	de | en	Optional
  designId	string (uuid)	Optional	Gespeichertes Briefdesign für diese Vorschau.
  design	Objekt	Optional	Ungespeichertes Briefdesign nur für diese Vorschau. Hat Vorrang vor designId und erzeugt keinen Eintrag im Konto. Eigenständige Formulare rendern mit documentMode: "form".
  reference	Objekt	Optional	Werte für diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie füllen Infoblock und Barcode in der Vorschau.
  senderProfileId	string (uuid)	Optional
  pages	integer	Optional	Wie viele Seiten als Bild zurückkommen. Standard 3, Maximum 8. Der PDF-Link enthält alle Seiten.
  resolution	thumb | full	Optional	thumb (96 dpi, Standard, schnell und klein) oder full (150 dpi, zum Prüfen von Details).
  templateId	string (uuid)	Optional
  templateVersionId	string (uuid)	Optional	Freigegebene Vorlagenversion, zusammen mit templateId und templateMergeValues: zeigt genau den Brief, den order_send damit verschickt.
  templateMergeValues	Objekt	Optional
  recipientAddressId	string (uuid)	Optional	Empfänger aus dem Adressbuch. Alternativ die recipient-Felder; fehlt beides, steht ein Musterempfänger im Fenster.
  recipientName	string	Optional
  recipientCompany	string	Optional
  recipientStreet	string	Optional
  recipientHouseNumber	string	Optional
  recipientZip	string	Optional
  recipientCity	string	Optional
  recipientCountry	string	Optional	ISO-3166-alpha-2, Standard DE.

• template_previewScope: template:read

  Rendert eine GESPEICHERTE Vorlage mit Beispielwerten und liefert Inline-PNGs, PDF-Link und designRender. designId oder ein ungespeichertes design bestimmen das Briefpapier; eigenständige Formulare rendern mit documentMode: "form". Die Vorschau ist kostenfrei und rein zum Ansehen. Ein blocks-Layout, das erst entsteht, rendert letter_preview; eine fertige Version speichert template_save (technischer Tool-Name template_save).

  Feld	Typ
  templateId	string (uuid)	Pflicht	Id der Vorlage aus template_list / template_get.
  versionId	string (uuid)	Optional	Exakte Vorlagenversion, die geprüft werden soll. Ohne Angabe gilt die freigegebene Version, danach der neueste Entwurf.
  designId	string (uuid)	Optional	Gespeichertes Briefdesign für diese Vorlagenvorschau.
  designVersionId	string (uuid)	Optional	Exakte unveränderliche Briefkopf-Version für diese Vorschau.
  design	Objekt	Optional	Ungespeichertes Briefdesign nur für diese Vorschau. Formulare rendern mit documentMode: "form".
  pages	integer	Optional	Wie viele Seiten als Bild zurückkommen. Standard 1, Maximum 3. 0: nur PDF-Link.

  Fehlercodes: NOT_FOUND

• document_listScope: letter:read

  Listet die erzeugten Dokumente des Kontos (Rechnung, Zahlungserinnerung, Mahnung, Gutschrift), neueste zuerst, gefiltert nach Art, Mandant, Empfänger oder Bezugsbeleg. Nächster Schritt: document_get liefert die vollständigen Belegdaten, document_create legt mit references einen Folgebeleg dazu an.

  Feld	Typ
  documentType	rechnung | zahlungserinnerung | mahnung | gutschrift	Optional
  mandantennummer	string	Optional
  recipientQuery	string	Optional	Freitext über Name, Firma oder Ort des Empfängers.
  referencesDocumentId	string (uuid)	Optional	Nur Dokumente, die sich auf dieses FrankKi-Dokument beziehen (z. B. alle Mahnungen zu einer Rechnung).
  referencesNumber	string	Optional
  since	string (date-time)	Optional
  limit	integer	Optional	Standard 20, maximal 100.
  offset	integer	Optional	Versatz für die Seitennavigation. Standard 0.

• document_getScope: letter:read

  Liefert ein Dokument mit allen Belegdaten (Positionen, Summen, USt-Sätze, Bezug) sowie letterId und orderId des Briefs, in dem es steckt. Das Feld referencePrefill enthält den fertigen references-Block für einen Folgebeleg: document_create übernimmt ihn unverändert als document.references für Mahnung, Zahlungserinnerung oder Gutschrift. Unter exports liefert FrankKi für versendete Rechnungen und Gutschriften signierte Download-Links: zugferdPdfUrl ist ein PDF/A-3 mit eingebetteter EN-16931-XML (ZUGFeRD), xrechnungXmlUrl die reine XRechnung-XML. Beide sind zum Herunterladen und Archivieren gedacht; die Übermittlung an ein Portal liegt beim Partner. Fehlt ein Export, nennt das Feld den Grund: DOCUMENT_EXPORT_NOT_READY heißt vorläufig, ein späterer Aufruf liefert den Export (Versand oder Freischaltung stehen noch aus), DOCUMENT_EXPORT_NOT_SUPPORTED heißt dauerhaft (der Export gilt für Rechnungen und Gutschriften; für Mahnung und Zahlungserinnerung trägt die Rechnung, auf die sie sich beziehen, den Export). Nächster Schritt: order_status verfolgt den Versand, document_create legt mit references eine Mahnung oder Gutschrift dazu an.

  Feld	Typ
  documentId	string (uuid)	Pflicht

Aktion

• sender_profile_upsertScope: sender_profile:writekein dryRun

  Legt ein Absenderprofil an oder bearbeitet es: Rechtsform, Pflichtangaben, optional Bankverbindung, Haftungsausschluss und Standard-Briefpapier. Ein unvollständiges Profil wird gespeichert und meldet die fehlenden Felder zurück, sodass es sich schrittweise ergänzen lässt. Versenden ist mit vollständigen Pflichtangaben möglich.

  Feld	Typ
  id	string	Optional	ID eines bestehenden Profils zum Bearbeiten, dann genügen die geänderten Felder. null in pflichtangaben entfernt ein Feld. Wechselt die Rechtsform, fallen die Felder der alten Form weg. Weglassen legt ein neues an.
  rechtsform	string	Optional	Rechtsform des Absenders, zum Beispiel gmbh, ug, gbr, verein, freiberufler. Sie bestimmt die verlangten Pflichtangaben.
  pflichtangaben	Objekt	Optional	Pflichtangaben als Objekt, zum Beispiel firmenname, strasse, plz, ort, land, registergericht, ustIdNr. sender_profile_validate nennt die je Rechtsform verlangten Felder.
  bankverbindung	Objekt	Optional	Optionale Bankverbindung mit iban, bic und bankname, unabhängig von der Vollständigkeit. Sie steht in der Fußzeile und unter Rechnungen.
  disclaimer	string	Optional	Optionaler Haftungsausschluss oder Fußzeilentext, unabhängig von der Vollständigkeit.
  displayName	string	Optional	Optionaler Anzeigename in Listen.
  isDefault	boolean	Optional	true macht dieses Profil zum Standardabsender; jedes andere verliert die Markierung. Das erste angelegte Profil wird automatisch Standard.
  defaultDesignId	stringnull	Optional	Briefpapier für Briefe, die selbst keines nennen. Weglassen behält den Wert, null löscht ihn.

• address_upsertScope: address:writekein dryRun

  Legt eine Adresse im Partner-Adressbuch an oder aktualisiert sie. Validiert die Adresse anhand landesspezifischer Regeln.

  Feld	Typ
  addressId	string (uuid)	Optional
  name	string	Pflicht
  company	string	Optional
  street	string	Pflicht
  houseNumber	string	Optional
  pobox	string	Optional
  zip	string	Optional
  city	string	Pflicht
  country	string	Optional	ISO-3166-alpha-2, default DE.
  mandantennummer	string	Optional
  addressType	recipient | sender | billing	Optional
  isDefault	boolean	Optional

  Fehlercodes: ADDRESS_INVALID

• letter_create_draftScope: order:sendkein dryRun

  Legt einen Briefentwurf an: erstellt eine Vorschau-PDF im hinterlegten Briefdesign (nur der Brieftext), speichert den Entwurf und liefert Seitenzahl, Vorschau-Link (24 Stunden gültig) und eine unverbindliche Kostenvorschau. Der Entwurf bleibt kostenfrei liegen, bis er versendet wird. Der Brieftext ist entweder content (Fließtext) ODER blocks (strukturiert: Tabellen, Überschriften, Summenzeilen), genau eines von beiden. Kompaktes blocks-Beispiel: {"blocks":[{"type":"heading","text":"Rechnung"},{"type":"table","columns":[{"key":"text","label":"Artikel","width":"grow"},{"key":"sum","label":"Summe","align":"right","format":"eur"}],"rows":[{"text":"Beratung","sum":32000}]},{"type":"totals","lines":[{"label":"Gesamt","amountCents":32000,"emphasis":true}]}]} Schema-Referenz inkl. styleDefs und Limits: MCP-Ressource frankki://blocks-guide. Die ersten Seiten kommen als Bild zurück und zeigen Betreff, Anschrift im Adressfenster, Absender, Datum und Umbrüche so, wie sie gedruckt werden. Die eingebettete Karte ist die Vorschau für den Menschen; PDF-Link und Brieftext stehen zusätzlich im Ergebnis, für reine Textansichten. Gemeldete Auffälligkeiten stehen in warnings. Ein neuer Aufruf legt einen korrigierten Entwurf an; ein gedruckter Brief ist endgültig. Für eine Mahnung, Kündigung, Mieterhöhung oder einen anderen Brief mit Frist gibt es das Einschreiben mit Nachweis; seinen Preis liefert shipping_quote. Nächster Schritt mit der zurückgegebenen letterId: letter_preview zeigt den Entwurf als Bild zum Nachbessern, order_send versendet ihn, letter_schedule versendet ihn zu einem späteren Zeitpunkt.

  Feld	Typ
  subject	string, max. 200 Zeichen	Pflicht
  content	string, max. 30000 Zeichen	Optional	Brieftext als Fließtext. Genau eines von content und blocks.
  blocks	Array<unbekannt> (min 1, max 200)	Optional	Strukturierter Briefinhalt als typisierte Blöcke, an Stelle von content. Limits: 200 Blöcke, 100 Zeilen/Tabelle, 20 Spalten, 2000 Zeichen/Zelle, 10 Bilder, 262144 Bytes.
  styleDefs	Objekt	Optional	Benannte Stile für das ganze Dokument (max. 24). Blöcke referenzieren sie über style.
  language	de | en	Optional	Standard de.
  senderAddressId	string (uuid)	Optional
  senderProfileId	string (uuid)	Optional	Absenderprofil, mit dem später versendet wird. Für die Vorschau zählt daraus nur das Standard-Briefdesign.
  recipientAddressId	string (uuid)	Optional	Eine gespeicherte Adresse aus dem Adressbuch (address_list) als Empfänger. Gleichwertig: recipientAddressInline oder die Felder recipientName bis recipientCountry wie bei order_send.
  recipientName	string	Optional
  recipientCompany	string	Optional
  recipientStreet	string	Optional
  recipientHouseNumber	string	Optional
  recipientZip	string	Optional
  recipientCity	string	Optional
  recipientCountry	string	Optional
  recipientAddressInline	Objekt	Optional
  presetName	string	Optional
  includeSignature	boolean	Optional	true setzt die hinterlegte Unterschrift unter den Brieftext. Standard aus, wie beim Versand.
  signatureId	string (uuid)	Optional	Eine bestimmte gespeicherte Unterschrift an Stelle der zuerst hinterlegten.
  clientLetterId	string	Optional	Idempotenzschlüssel. Ein erneuter Aufruf mit demselben Wert UND derselben Nutzlast liefert denselben Entwurf, statt einen zweiten anzulegen. Ein anderer Brief braucht einen neuen Schlüssel: derselbe Schlüssel mit anderem Inhalt endet mit IDEMPOTENCY_CONFLICT, und es entsteht kein Entwurf.
  designId	string (uuid)	Optional	Gespeichertes Briefdesign für diesen Brief. Es wird bereits in der Vorschau-PDF gerendert und am Entwurf gespeichert, sodass ein späterer Versand über die letterId es übernimmt (außer der Versand nennt selbst ein Design). Ohne Angabe gilt das Standard-Design des Absenderprofils, in der Vorschau wie beim Versand.
  reference	Objekt	Optional	Werte für diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie füllen den Infoblock und den Barcode.

• attachment_upload_pdfScope: order:sendkein dryRun

  Lädt ein PDF als Anhang zu einem Partner-Brief hoch. Prüft vor dem Speichern die Dateigröße (max. 50 MB) und die zusammengeführte Seitenzahl (max. 30 Seiten inkl. Brief und übriger Anhänge). Gedruckt wird nur A4 hochkant: eine andere Seite (US Letter, A5, quer) setzt FrankKi verkleinert auf A4, und die Antwort nennt sie in pageFormatNote.

  Feld	Typ
  letterId	string (uuid)	Pflicht
  pdfUrl	string	Optional	Öffentliche URL des PDF (Alternative zu pdfBase64).
  pdfBase64	string	Optional	PDF als Base64 (Alternative zu pdfUrl).
  title	string	Optional
  position	integer	Optional

• attachment_upload_imageScope: order:sendkein dryRun

  Lädt ein Bild (PNG/JPEG) als Anhang zu einem Partner-Brief hoch. Das Bild wird serverseitig auf eine A4-PDF-Seite skaliert (optional gedreht) und wie ein PDF gespeichert. Prüft vor dem Speichern die zusammengeführte Seitenzahl (max. 30 Seiten). Die EXIF-Orientierung wird automatisch in die Pixel eingerechnet, ein Handyfoto steht also von selbst aufrecht. rotation dreht das Bild zusätzlich um die angegebenen Grad weiter; 0 lässt es so, wie es hochgeladen wurde.

  Feld	Typ
  letterId	string (uuid)	Pflicht
  imageUrl	string	Optional	Öffentliche URL des Bildes (Alternative zu imageBase64).
  imageBase64	string	Optional	Bild als Base64 (Alternative zu imageUrl).
  rotation	0 | 90 | 180 | 270	Optional	Zusätzliche Drehung in Grad, im Uhrzeigersinn. Die EXIF-Orientierung des Bildes wird bereits automatisch in die Pixel eingerechnet, das Bild steht also von sich aus richtig. Dieser Wert dreht es danach ein zweites Mal. Für ein Handyfoto ist deshalb 0 richtig.
  title	string	Optional
  position	integer	Optional

• letter_upload_pdfScope: order:sendkein dryRun

  Lädt einen fertigen Brief als PDF hoch, der genau so verschickt wird, wie er ist. Die Prüfung schaut, ob die Empfängeradresse im Adressfeld der Versandart steht. Beim Standardbrief liegt es 60 bis 85,5 mm von oben, beim Einschreiben 68 bis 85,5 mm, jeweils 22 bis 107,5 mm von links. Der übrige Fensterbereich bleibt leer, an jeder Kante bleiben 5 mm frei, und jede Seite ist A4 hochkant. Zurück kommen pdfStorageKey, die Funde mit den Millimetern zum Verschieben und Seite 1 mit eingezeichneten Zonen. sendable sagt, ob order_send diesen pdfStorageKey annimmt. Weichen nur PLZ oder Ort ab, lassen sich entweder die Empfängerfelder oder die PDF korrigieren; jeder andere Fund braucht eine korrigierte PDF und einen neuen Upload. Kostenlos.

  Feld	Typ
  pdfBase64	string	Optional	Die Brief-PDF als Base64 (Alternative zu pdfUrl).
  pdfUrl	string	Optional	Öffentliche URL der Brief-PDF (Alternative zu pdfBase64).
  deliveryType	standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered	Optional	Versandart, für die das Adressfeld geprüft wird; dieselbe wie später bei order_send. Standard standard.
  recipientZip	string	Optional	Optional: PLZ des Empfängers, wird mit der gedruckten Adresse verglichen.
  recipientCity	string	Optional	Optional: Ort des Empfängers, wird mit der gedruckten Adresse verglichen.

• order_sendScope: order:senddryRun verfügbar

  Versendet einen Brief per Post: prüft die Pflichtangaben des Absenders, die Empfängeradresse, den AVV und die Limits, erstellt die PDF und berechnet den Preis. Der Brief kommt über letterId (ein Entwurf) oder inline: dann ist der Text content (Fließtext) oder blocks (strukturiert: Tabellen, Überschriften, Summenzeilen), genau eines von beiden. Kompaktes blocks-Beispiel: {"blocks":[{"type":"heading","text":"Rechnung"},{"type":"table","columns":[{"key":"text","label":"Artikel","width":"grow"},{"key":"sum","label":"Summe","align":"right","format":"eur"}],"rows":[{"text":"Beratung","sum":32000}]},{"type":"totals","lines":[{"label":"Gesamt","amountCents":32000,"emphasis":true}]}]} Schema-Referenz: frankki://blocks-guide. dryRun: true ist eine kostenfreie Probe: sie liefert Preis, Seite 1 als Bild und die Liste checks (jede Prüfung mit passed, failed oder skipped), und der Brief bleibt unversandt; ein zweiter Aufruf mit denselben Werten und dryRun: false versendet genau diesen Brief. Ein echter Versand wartet auf Freigabe. Autopilot ist eine Dashboard-Einstellung, die die Person selbst steuert: mit ihm geht ein Standardbrief aus eigener freigegebener Vorlage (templateId plus templateVersionId) an einen Empfänger aus dem Adressbuch nach 10 Minuten raus. saveRecipient: true trägt den Empfänger dabei ein, humanSummary nennt die Uhrzeit, order_status und order_cancel nehmen die approvalId. mcp_health meldet unter setup, welcher Freigabeweg gilt. Für eine Mahnung, Kündigung, Mieterhöhung oder einen anderen Brief mit Frist gibt es das Einschreiben mit Nachweis; seinen Preis liefert shipping_quote. Eine fertige eigene PDF geht unverändert raus: letter_upload_pdf prüft und speichert sie, order_send versendet sie dann mit pdfStorageKey und Empfänger.

  Feld	Typ
  letterId	string (uuid)	Optional	Bestehender Entwurf. Alternativ kommt der Brief inline.
  pdfStorageKey	string	Optional	Der Schlüssel aus letter_upload_pdf, wenn eine eigene fertige PDF der Brief ist, an Stelle von Betreff und Text. Dazu gehören die Empfängerfelder, so wie sie auf der PDF stehen, und die deliveryType. Der Versand prüft, ob die Adresse im Adressfeld der Versandart steht, beim Standardbrief 60 bis 85,5 mm von oben, beim Einschreiben 68 bis 85,5 mm. Steht sie woanders, nennt PDF_LAYOUT_INVALID die Millimeter zum Verschieben.
  subject	string, max. 200 Zeichen	Optional
  content	string, max. 30000 Zeichen	Optional	Brieftext als Fließtext. Genau eines von content und blocks.
  blocks	Array<unbekannt> (min 1, max 200)	Optional	Strukturierter Briefinhalt als typisierte Blöcke, an Stelle von content. Limits: 200 Blöcke, 100 Zeilen/Tabelle, 20 Spalten, 2000 Zeichen/Zelle, 10 Bilder, 262144 Bytes.
  styleDefs	Objekt	Optional	Benannte Stile für das ganze Dokument (max. 24). Blöcke referenzieren sie über style.
  recipientAddressId	string (uuid)	Optional	Eine gespeicherte Adresse aus dem Adressbuch (address_list) als Empfänger, an Stelle der Felder recipientName bis recipientCountry.
  recipientName	string	Optional
  recipientCompany	string	Optional
  recipientStreet	string	Optional
  recipientHouseNumber	string	Optional
  recipientZip	string	Optional
  recipientCity	string	Optional
  recipientCountry	string	Optional	ISO-3166-alpha-2, Standard DE.
  priceVersion	string	Optional	Optional: die priceVersion aus einem vorherigen shipping_quote. Weicht der Preis beim Versand davon ab, wird mit PRICE_CHANGED abgebrochen, bevor etwas berechnet wird.
  quotedUnitPriceCents	integer	Optional	Optional: der Stückpreis in Cent aus einem vorherigen shipping_quote (unitPriceCents). Ist er gesetzt, entscheidet er den PRICE_CHANGED-Abgleich und liefert den alten Preis im Fehler mit.
  deliveryType	standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered	Optional	Standard standard.
  express	boolean	Optional
  color	boolean	Optional	Ohne Angabe wird die Farbe automatisch erkannt.
  includeSignature	boolean	Optional
  signatureId	string (uuid)	Optional
  letterheadId	string (uuid)	Optional	Bestimmter Briefkopf für diesen Versand. Ohne Angabe wird der Standard-Briefkopf verwendet.
  letterheadEnabled	boolean	Optional	false lässt den Briefkopf für diesen einen Versand weg.
  senderAddressId	string (uuid)	Optional
  senderProfileId	string (uuid)	Optional
  mandantennummer	string	Optional
  clientOrderId	string, max. 200 Zeichen	Optional	Idempotenzschlüssel: eine beliebige Zeichenkette (1-200 Zeichen, z. B. 'mahnung-kunde42-2026-07-20'; kein UUID-Format nötig). Ein erneuter Aufruf mit demselben Wert liefert dieselbe Bestellung, statt ein zweites Mal zu versenden. Der Namensraum 'approval:' ist reserviert.
  scheduledAt	string (date-time)	Optional
  approvalMode	auto | draft | review	Optional	Wie der Versand freigegeben wird. 'draft' und 'review' stellen ihn in die Freigabe-Warteschlange, statt sofort zu versenden. 'auto' wird derzeit genauso behandelt wie 'review': der Brief wartet auf die Freigabe durch einen Menschen. Mit einem Test-Token läuft jeder Modus als Probe. Auch diese beiden reservieren den Betrag beim Einreichen im Wallet, damit ein freigegebener Brief später nicht am Guthaben scheitert. Ohne Deckung kommt INSUFFICIENT_FUNDS zurück und es wird nichts angelegt. Einen Entwurf ohne Wallet-Deckung legt letter_create_draft an.
  maxCostEuros	number	Optional	Maximalbetrag in Euro. Liegt der Preis darüber, wird abgebrochen.
  presetName	string	Optional
  auditTag	string	Optional
  templateId	string (uuid)	Optional
  templateVersionId	string (uuid)	Optional	Exakte freigegebene Vorlagenversion. Nur gemeinsam mit templateId; der Server rendert sie mit templateMergeValues neu und ignoriert mitgesendeten Betreff/Inhalt.
  templateMergeValues	Objekt	Optional	Merge-Werte für die exakte Vorlagenversion.
  coverTemplateId	string (uuid)	Optional	Anschreiben für eine eigenständige Formularvorlage.
  coverTemplateVersionId	string (uuid)	Optional	Exakte freigegebene Version des Anschreibens.
  designId	string (uuid)	Optional	Gespeichertes Briefdesign für diesen Versand. Ohne Angabe gilt in dieser Reihenfolge: das am Entwurf gespeicherte Design (beim Versand über letterId), sonst das Standard-Design des Absenderprofils, sonst keins.
  design	Objekt	Optional	Exakter Briefdesign-Snapshot aus template_apply_with_merge_fields.composition.design. Hat Vorrang vor designId und verhindert, dass eine spätere Designänderung die freigegebene Vorlagenkomposition verändert.
  reference	Objekt	Optional	Werte für diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie füllen den Infoblock und den Barcode.
  dryRun	boolean	Optional	Probe ohne Kosten; liefert Seite 1 als Bild und die Liste checks (jede Prüfung mit passed, failed oder skipped).
  saveRecipient	boolean	Optional	true übernimmt den Empfänger mit diesem Versand ins Adressbuch (für Autopilot).
  includeGeometry	boolean	Optional	Liefert zusätzlich die Layoutdaten der Seiten.

  Idempotenzschlüssel: clientOrderId (siehe Konventionen).

  Fehlercodes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, DAILY_CAP_EXCEEDED, MANDANT_CAP_EXCEEDED, COST_OVER_LIMIT, CONTENT_REJECTED, COUNTRY_NOT_SUPPORTED, LEGAL_PROOF_UNAVAILABLE_FOR_COUNTRY, PRICE_UNAVAILABLE, PDF_LETTER_UNSUPPORTED, SANDBOX_DISABLED, IDEMPOTENCY_CONFLICT, DESIGN_NOT_FOUND, DESIGN_RENDER_FAILED, DESIGN_ZONE_VIOLATION

• approval_submitScope: order:senddryRun verfügbar

  Reicht einen Brief zur menschlichen Freigabe ein: prüft Pflichtangaben, Empfänger, AVV und Limits, erstellt die finale PDF, berechnet den Preis, reserviert die Kosten und legt eine Freigabe in der Warteschlange an. Sie wartet auf die Entscheidung eines Menschen, auch mit Autopilot. Die eingebettete Karte ist Vorschau und Freigabe. PDF-Link und Brieftext stehen zusätzlich im Ergebnis, für reine Textansichten. Mit approval:self_approve zeigt die Karte Freigeben und Ablehnen. In allen anderen Fällen führt sie ins angemeldete Portal. Mit dryRun bleiben Guthaben und Warteschlange unberührt, und die Antwort enthält die Liste checks (jede Prüfung mit passed, failed oder skipped).

  Feld	Typ
  letterId	string (uuid)	Optional	Bestehender Entwurf. Alternativ kommt der Brief inline.
  subject	string, max. 200 Zeichen	Optional
  content	string, max. 30000 Zeichen	Optional
  recipientAddressId	string (uuid)	Optional	Eine gespeicherte Adresse aus dem Adressbuch (address_list) als Empfänger, an Stelle der Felder recipientName bis recipientCountry.
  recipientName	string	Optional
  recipientCompany	string	Optional
  recipientStreet	string	Optional
  recipientHouseNumber	string	Optional
  recipientZip	string	Optional
  recipientCity	string	Optional
  recipientCountry	string	Optional	ISO-3166-alpha-2, Standard DE.
  deliveryType	standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered	Optional	Standard standard.
  express	boolean	Optional
  color	boolean	Optional	Ohne Angabe wird die Farbe automatisch erkannt.
  includeSignature	boolean	Optional
  signatureId	string (uuid)	Optional
  senderAddressId	string (uuid)	Optional
  senderProfileId	string (uuid)	Optional
  mandantennummer	string	Optional
  clientOrderId	string	Optional	Idempotenzschlüssel. Ein erneuter Aufruf mit demselben Wert liefert dieselbe Freigabe, statt ein zweites Mal einzureichen. Der Präfix 'approval:' ist reserviert.
  scheduledAt	string (date-time)	Optional
  approvalMode	auto | draft | review	Optional
  maxCostEuros	number	Optional	Maximalbetrag in Euro. Liegt der Preis darüber, wird abgebrochen.
  presetName	string	Optional
  auditTag	string	Optional
  templateId	string (uuid)	Optional
  reason	string, max. 500 Zeichen	Optional	Kurzer Grund für die Freigabe, den die prüfende Person auf der Karte liest.
  requesterContext	string, max. 500 Zeichen	Optional	Zusatzkontext zur einreichenden Person oder zum Anlass.
  dryRun	boolean	Optional

  Idempotenzschlüssel: clientOrderId (siehe Konventionen).

  Fehlercodes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, DAILY_CAP_EXCEEDED, MANDANT_CAP_EXCEEDED, COST_OVER_LIMIT, CONTENT_REJECTED, IDEMPOTENCY_CONFLICT

• approval_decideScope: approval:decidekein dryRun

  Gibt eine wartende Freigabe frei oder lehnt sie ab. 'approve' setzt voraus, dass diese OAuth-Verbindung die zusätzlich erteilte Berechtigung approval:self_approve trägt. Fehlt diese Berechtigung, öffnet der Mensch den zurückgegebenen approvalUrl und entscheidet im angemeldeten Portal. approval:decide bleibt ebenfalls erforderlich. Bei Freigabe durch den Agenten geht der Brief nach 10 Minuten raus und kann bis dahin mit order_cancel gestoppt werden.

  Feld	Typ
  approvalId	string (uuid)	Pflicht
  decision	approve | reject	Pflicht
  comment	string, max. 1000 Zeichen	Optional
  clientOrderId	string	Optional

  Idempotenzschlüssel: clientOrderId (siehe Konventionen).

  Fehlercodes: APPROVAL_ALREADY_DECIDED, NOT_FOUND

• order_cancelScope: order:sendkein dryRun

  Storniert einen Brief und schreibt den Betrag dem Wallet des Kontos gut (geschlossener Kreislauf, Gutschrift ins Wallet statt auf die Karte). Mit orderId wird eine bereits erstellte Bestellung im Stornofenster storniert; ist der Brief bereits im Druck, wird sauber abgelehnt. Mit approvalId wird eine per Chat freigegebene Sendung im 10-Minuten-Stornofenster gestoppt, bevor sie überhaupt versendet wird (der Mensch sagt 'stopp').

  Feld	Typ
  orderId	string (uuid)	Optional	Die zu stornierende Bestellung.
  approvalId	string (uuid)	Optional	An Stelle von orderId: stoppt eine per Chat freigegebene Sendung im 10-Minuten-Stornofenster, bevor sie versendet wird (der Mensch sagt 'stopp').
  reason	string, max. 500 Zeichen	Optional	Optionaler Stornogrund.

  Fehlercodes: NOT_FOUND

• template_saveScope: template:writekein dryRun

  Speichert eine Vorlage als ENTWURF (Vorlage speichern, Vorlagenversion speichern, Vorlagenentwurf anlegen). documentKind ist letter oder form. Briefkopf und Marke sind eine externe Schicht, die erst bei Vorschau oder Versand aufgelöst wird, und bleiben außerhalb der Vorlage. designId bleibt nur als veralteter Hinweis zur Ableitung der Dokumentart kompatibel; explizites documentKind gewinnt. Ein Formular lässt sich eigenständig speichern. coverTemplateId kann eine Anschreibenversion für ein Paket pinnen. Fehlt templateId, entsteht eine neue Vorlage; mit templateId eine neue Entwurfsversion. Der Entwurf wird mit der Freigabe nutzbar; die Antwort enthält den Prüflink. Der technische Tool-Name ist template_save. Der Vorlageninhalt ist entweder contentTemplate (Fließtext) ODER blocksTemplate (strukturiert: Tabellen, Überschriften, Summenzeilen), genau eines von beiden. Merge-Felder sind typisiert (text, date, number, currency, rows); ein Tabellenblock bindet eine rows-Liste über rowsFrom. Der schnellste Start ist eine Standardvorlage aus template_get, kopiert und angepasst. letter_preview rendert den Stand vor dem Speichern, Seite für Seite neben dem Original; ein Nachbau ist fertig, wenn Seitenzahl und wesentliche Geometrie zum Original passen. Eigenständige Formulare rendern in letter_preview mit einem design im documentMode "form".

  Feld	Typ
  templateId	string (uuid)	Optional	Bestehende Vorlage: es entsteht eine NEUE Entwurfsversion. Ohne Angabe wird eine neue Vorlage angelegt.
  name	string	Pflicht	Name der Vorlage.
  kategorie	stringnull	Optional	Fachliche Kategorie, z.B. kuendigung (der Wert ist ein Schlüssel und bleibt so geschrieben).
  subjectTemplate	string	Pflicht	Betreffvorlage, darf {{platzhalter}} enthalten.
  contentTemplate	string	Optional	Inhaltsvorlage als Fließtext, darf {{platzhalter}} enthalten. Entweder contentTemplate ODER blocksTemplate.
  blocksTemplate	Array<unbekannt> (min 1, max 200)	Optional	Strukturierte Inhaltsvorlage (Tabellen, Überschriften, Summenzeilen). Textfelder dürfen {{platzhalter}} enthalten; ein Tabellenblock kann mit rowsFrom: "<schlüssel>" ein Merge-Feld vom Typ rows binden und bekommt dessen Zeilen beim Anwenden. Entweder contentTemplate ODER blocksTemplate.
  styleDefs	Objekt	Optional	Benannte Stile der Blockvorlage. Nur zusammen mit blocksTemplate.
  mergeFields	Array<Objekt> (max 100)	Optional	Die Platzhalter der Vorlage.
  approvalModeRecommended	auto | review | draft |	Optional	Empfohlener Freigabemodus für Briefe aus dieser Vorlage.
  documentKind	letter | form	Optional	Unveränderliche Dokumentart der Vorlagenversion. letter ist direkt adressierbar, form benötigt ein Anschreiben.
  designId	string (uuid)	Optional	Veralteter Autor-Hinweis zur Ableitung von documentKind. Das Design wird nicht in der Vorlage gespeichert. Explizites documentKind gewinnt.
  clearDesign	boolean	Optional	Veralteter kompatibler Autor-Hinweis. Es gibt keine Design-Bindung an neuen Vorlagenversionen.
  coverTemplateId	string (uuid)	Optional	Deckvorlage für ein Formular ohne Empfängerblock. Beim Speichern wird exakt ihre aktuelle freigegebene Version gepinnt.
  clearCoverTemplate	boolean	Optional	Entfernt die geerbte Deckvorlagen-Bindung. Ohne coverTemplateId und ohne clearCoverTemplate erbt eine neue Version die bisherige Bindung.

  Fehlercodes: NOT_FOUND, TEMPLATE_SLUG_CONFLICT

• template_releaseScope: template:writekein dryRun

  Gibt eine Entwurfsversion frei, sodass sie versendet werden kann; letzter Schritt der Gestaltungskette (template_get, anpassen, letter_preview, template_save, template_preview, template_release). template_preview zeigt dem Menschen eine Freigabekarte mit Freigeben-Knopf. template_release macht die Version sofort versandbereit, an dieser Karte vorbei, die die Person sonst selbst bestätigt; die Antwort vermerkt die Freigabe als Freigabe durch den Agenten. Über MCP geht das bei einem Konto mit genau einem aktiven Nutzer. Bei mehreren Nutzern gibt ein Mensch im Dashboard frei (Vier-Augen-Prinzip), und die Antwort enthält den Link dorthin. Danach füllt template_apply_with_merge_fields die Vorlage mit Werten, und letter_create_draft oder order_send verschickt das Ergebnis.

  Feld	Typ
  templateId	string (uuid)	Pflicht
  versionId	string (uuid)	Pflicht	Die freizugebende Entwurfsversion.

  Fehlercodes: NOT_FOUND, TEMPLATE_VERSION_NOT_DRAFT, TEMPLATE_FOUR_EYES_REQUIRED

• template_archiveScope: template:writekein dryRun

  Archiviert eine Vorlage. Sie verschwindet aus den Listen und aus dem Versand, bleibt aber erhalten. Der Inhalt bleibt vollständig erhalten, und ein erneuter Aufruf ist unschädlich.

  Feld	Typ
  templateId	string (uuid)	Pflicht

  Fehlercodes: NOT_FOUND

• template_draft_discardScope: template:writekein dryRun

  Verwirft eine Entwurfsversion, solange sie noch auf ihre Freigabe wartet. Freigegebene und ersetzte Versionen bleiben unantastbar und vollständig erhalten. Ein erneuter Aufruf ist unschädlich.

  Feld	Typ
  templateId	string (uuid)	Optional	Optional. Bindet die Version zusätzlich an diese Vorlage.
  versionId	string (uuid)	Pflicht	Die zu verwerfende Entwurfsversion.

  Fehlercodes: NOT_FOUND, TEMPLATE_VERSION_IMMUTABLE

• template_clone_from_libraryScope: template:writekein dryRun

  template_clone_from_library kopiert ein bis fünf FrankKi-Standardvorlagen in einem Aufruf in die eigenen Vorlagen des Kontos, etwa Rechnung, Mahnung, Angebot, Kündigung oder Behördenpost, und zeigt die erste als Bild. Mit release true gibt es sie frei, wenn das Konto genau einen aktiven Nutzer hat. Danach sendet order_send mit templateId und templateVersionId.

  Feld	Typ
  items	Array<Objekt> (min 1, max 5)	Pflicht	Ids aus mcp_health oder template_list (curated).
  release	boolean	Optional	Gibt frei, wenn das Konto genau einen aktiven Nutzer hat.
  previewFirst	boolean	Optional

• preset_saveScope: preset:writekein dryRun

  Speichert eine benannte Voreinstellung (Konfigurations-Bundle) im Partnerprofil. Der Name ist pro Partner eindeutig. Limits in der Voreinstellung werden unverändert gespeichert und dienen als Notiz. Durchgesetzt werden ausschließlich die im Web gesetzten Konto- und Sub-Wallet-Limits.

  Feld	Typ
  name	string	Pflicht	Eindeutiger Name der Voreinstellung (pro Partner).
  preset	Objekt	Pflicht	Das Konfigurations-Bundle (Absender/Unterschrift/Briefkopf, Versand, Kennzeichnung, Freigabe, Planung, Limits, auditTagPrefix).

• signature_uploadScope: signature:writekein dryRun

  Lädt eine Unterschrift als PNG hoch und speichert sie im Partnerprofil. Die Unterschrift wird beim Versand unterhalb des Brieftexts eingefügt. Nur PNG wird unterstützt.

  Feld	Typ
  pngBase64	string	Pflicht	Die Unterschrift als PNG (Base64).
  widthMm	number	Optional	Gewünschte Breite in mm (optional).
  displayName	string	Optional	Anzeigename der Unterschrift (optional).

• letterhead_uploadScope: letterhead:writekein dryRun

  Lädt einen Briefkopf als PNG oder PDF hoch und speichert ihn im Partnerprofil. Quelle ist entweder fileUrl oder fileBase64, genau eine von beiden; fileUrl hält die Datei aus dem Aufruf heraus. PNG wird auf die Seite gedruckt; ein PDF-Briefkopf wird vorerst nur abgelegt, gedruckt wird bisher nur PNG (rendered=false). Beim Nachbau eines vorhandenen Briefs: Logo und Titelblock aus dem Kopf der Seite gehören hierher (dann letter_design_save); der Brieftext bleibt den blocks vorbehalten.

  Feld	Typ
  fileBase64	string	Optional	Der Briefkopf als PNG oder PDF (Base64), Alternative zu fileUrl.
  fileUrl	string	Optional	Öffentliche http(s)-URL des Briefkopfs (PNG oder PDF), Alternative zu fileBase64. fileUrl überträgt die Datei in voller Farbtiefe, ohne sie inline in den Aufruf zu legen; ein farbreduziertes Base64-Bild druckt sichtbar schlechter. Maximal 20 MB.
  widthMm	number	Optional	Breite in mm (optional).
  heightMm	number	Optional	Höhe in mm (optional).
  placement	header | footer | full	Optional	Platzierung auf der Seite.
  displayName	string	Optional	Anzeigename des Briefkopfs (optional).

• letter_design_saveScope: letter_design:writekein dryRun

  Speichert ein wiederverwendbares Briefpapier (Briefdesign) mit schemaVersion 1 oder 2 im Partnerprofil und gibt designId sowie den Hash der gespeicherten Quelldaten zurück. Dasselbe Briefpapier trägt danach jede Post: Kündigung, Rechnung, Mahnung, Angebot, Vertrag und Behördenpost. Der technische Tool-Name ist letter_design_save. Das Design wird vor dem Speichern vollständig validiert und gegen die Zustellzonen geprüft.

  Feld	Typ
  name	string, max. 120 Zeichen	Pflicht	Eindeutiger Name des Briefdesigns.
  design	unbekannt	Pflicht
  designId	string (uuid)	Optional
  brandingOwnershipConfirmed	boolean	Optional	Bei einer Neuanlage oder geänderten Branding-Asset-Referenz zwingend true. Unveränderte Folgespeicherungen brauchen keine erneute Bestätigung.

  Fehlercodes: DESIGN_ZONE_VIOLATION

• letter_design_deleteScope: letter_design:writekein dryRun

  Archiviert (löscht) ein gespeichertes Briefpapier (Briefdesign). Neue Sendungen laufen danach über die verbleibenden Briefpapiere, egal ob Kündigung, Rechnung, Mahnung, Angebot, Vertrag oder Behördenpost; bereits versendete Briefe behalten ihr Original zur Nachvollziehbarkeit.

  Feld	Typ
  designId	string (uuid)	Pflicht	Das zu löschende Briefdesign.

  Fehlercodes: NOT_FOUND

• brand_kit_saveScope: letter_design:writekein dryRun

  Speichert Logo-Referenzen, Farben und Schrift für das nutzerseitige Ergebnis Briefkopf & Marke. brandingOwnershipConfirmed muss true sein und bestätigt die Nutzungsrechte an den angegebenen Marken-Assets. Die Antwort enthält den gespeicherten Stand und den Prüflink. Technischer Tool-Name: brand_kit_save.

  Feld	Typ
  brandKit	Objekt	Pflicht
  brandingOwnershipConfirmed	boolean	Pflicht	Bestätigt die Nutzungsrechte an Logo und eigener Schrift. Muss true sein.

• brand_import_from_websiteScope: letter_design:writekein dryRun

  Liest eine öffentliche Firmenwebsite aus und schlägt daraus ein Briefkopf-Design vor: Markenfarben, Hausschriftzuordnung, Logo-Kandidaten und Firmendaten aus dem Impressum. Die gefundenen Logos landen als Design-Assets im Konto und sind sofort verwendbar. Das Ergebnis ist ein Vorschlag zur Abstimmung mit der Kundin oder dem Kunden; übernommen wird die Marke erst durch einen anschließenden Aufruf von brand_kit_save mit brandingOwnershipConfirmed. Technischer Tool-Name: brand_import_from_website.

  Feld	Typ
  websiteUrl	string, max. 2048 Zeichen	Pflicht	Öffentliche Adresse der Firmenwebsite, zum Beispiel https://beispiel.de.
  maxLogoCandidates	integer	Optional	Wie viele Logo-Kandidaten heruntergeladen und gespeichert werden. Standard 3.

• brand_setup_from_websiteScope: letter_design:writekein dryRun

  Firmenwebsite zu Absender, Marke und Briefpapier in zwei Aufrufen. apply false liest die Website und liefert einen Vorschlag: Logo, Farben, Schrift, Absenderprofil mit Pflichtangaben aus dem Impressum, Absenderadresse und ein passendes Briefpapier, dazu die fehlenden Pflichtangaben, die eine Frage an die Person und Seite 1 dieses Briefpapiers als Bild (letterheadPreview). apply true speichert alles auf einmal mit der proposalId daraus und brandingOwnershipConfirmed true: Marke, Absenderprofil, Absenderadresse, Briefpapier mit Logo als Standard, und zeigt eine Vorschau als Bild. Bestehende Angaben der Person bleiben erhalten, senderOverrides gehen vor. Nächster Schritt: template_clone_from_library. Technischer Tool-Name: brand_setup_from_website.

  Feld	Typ
  websiteUrl	string, max. 2048 Zeichen	Pflicht	Öffentliche Firmenwebsite, z.B. https://beispiel.de.
  apply	boolean	Optional	false liefert den Vorschlag, true speichert ihn.
  proposal	Objekt	Optional	Das proposal aus der Antwort mit apply false, gern von der Person korrigiert. Spart den zweiten Website-Abruf.
  proposalId	string	Optional	Bei apply true erforderlich: die proposalId aus der Antwort mit apply false, 30 Minuten gültig.
  brandingOwnershipConfirmed	boolean	Optional	Bei apply true erforderlich: die Person bestätigt, dass sie Logo und Marke verwenden darf.
  designPresetId	string	Optional	Briefpapier-Vorlage aus letter_design_list_presets. Standard ist der Vorschlag.
  senderOverrides	Objekt	Optional	Korrekturen und fehlende Angaben von der Person, sie gehen allem anderen vor.

• letter_scheduleScope: letter:scheduledryRun verfügbar

  Plant den Versand eines bestehenden Entwurfs für einen späteren Zeitpunkt (fester Termin, relative Verzögerung oder wiederkehrend per cron). Alle Prüfungen und der Preis werden sofort ermittelt und die Kosten reserviert. Eine echte OAuth-Verbindung legt zuerst eine Freigabe an. Die eingebettete Karte ist Vorschau und Freigabe. PDF-Link und Brieftext stehen zusätzlich im Ergebnis, für reine Textansichten. Eine OAuth-Verbindung mit approval:self_approve darf über die Karte entscheiden. Nach der Freigabe entsteht die Planung, der eigentliche Versand läuft zum geplanten Zeitpunkt durch dieselbe Versandpipeline und denselben Freigabeweg wie order_send.

  Feld	Typ
  letterId	string (uuid)	Pflicht	Bestehender Entwurf, der geplant versendet wird.
  mode	at | in | cron	Pflicht	at = fester Zeitpunkt, in = relative Verzögerung, cron = wiederkehrend.
  sendAt	string	Optional	Zeitpunkt bei mode='at' (ISO 8601, Berlin-Zeit wenn ohne Offset).
  delay	string	Optional	Verzögerung bei mode='in': '2d', '1w', '3h', 'next-business-day', 'next-monday', 'end-of-month'.
  cronExpression	string	Optional	5-Felder cron bei mode='cron': 'min std tag monat wochentag'.
  endDate	string	Optional	Enddatum für eine cron-Serie (ISO 8601, Berlin-Zeit wenn ohne Offset).
  businessDaysOnly	boolean	Optional	true versendet nur an Werktagen und verschiebt einen Termin am Wochenende oder Feiertag auf den nächsten Werktag zur selben Uhrzeit. Standard true.
  sendBeforeHour	number	Optional	Versand-Cutoff in Berliner Ortszeit, Standard 16. Ein Termin ab dieser Stunde rückt auf den nächsten Werktag (mit businessDaysOnly false: auf den nächsten Tag), jeweils 9:00 Uhr. timing im Ergebnis nennt Wunschtermin, tatsächlichen Termin und Grund.
  deliveryType	standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered	Optional
  express	boolean	Optional
  color	boolean	Optional
  includeSignature	boolean	Optional
  signatureId	string (uuid)	Optional
  senderAddressId	string (uuid)	Optional
  senderProfileId	string (uuid)	Optional
  mandantennummer	string	Optional
  presetName	string	Optional
  auditTag	string	Optional
  templateId	string (uuid)	Optional
  templateVersionId	string (uuid)	Optional	Exakte freigegebene Vorlagenversion, zusammen mit templateId. Der Entwurf liefert Empfänger und Anlagen. Betreff und Text rendert der Server bei jedem Versand aus der Vorlage und templateMergeValues. Der Autopilot prüft nur Planungen dieser Art.
  templateMergeValues	Objekt	Optional	Merge-Werte für die exakte Vorlagenversion.
  coverTemplateId	string (uuid)	Optional	Anschreiben für eine eigenständige Formularvorlage.
  coverTemplateVersionId	string (uuid)	Optional	Exakte freigegebene Version des Anschreibens.
  maxCostEuros	number	Optional	Maximalbetrag in Euro. Liegt der Preis darüber, wird abgebrochen.
  dryRun	boolean	Optional	Prüft und bepreist die Planung, legt aber nichts an und reserviert nichts. Liefert dryRunWouldHaveCost.

  Fehlercodes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, COST_OVER_LIMIT

• schedule_cancelScope: letter:scheduledryRun verfügbar

  Bricht eine geplante Sendung ab und gibt die dafür reservierte Summe im Wallet wieder frei. Die scheduleId liefern letter_schedule und schedule_list.

  Feld	Typ
  scheduleId	string (uuid)	Pflicht	Die abzubrechende Planung.
  dryRun	boolean	Optional	true liefert die Summe, die frei würde, ohne die Planung abzubrechen.

  Fehlercodes: NOT_FOUND

• order_send_batchScope: order:senddryRun verfügbar

  Reicht mehrere Briefe als einen Stapel ein. Jeder Eintrag wird einzeln geprüft und bepreist. Der Stapel landet als eine Freigabe für alle Empfänger in der Warteschlange. Mit Autopilot geht ein Stapel, dessen Briefe alle die Autopilot-Regeln erfüllen, nach 10 Minuten raus; order_cancel stoppt ihn bis dahin. Unter dem zurückgegebenen approvalUrl prüft der Mensch Empfängerliste, Anzahl und Gesamtkosten im angemeldeten Portal und entscheidet dort. Selbst freigeben kann eine OAuth-Verbindung mit der zusätzlich erteilten Berechtigung approval:self_approve. Bei Ablehnung wird die gesamte Reservierung zurückgebucht. Mit dryRun bleibt es bei einer kostenfreien Probe.

  Feld	Typ
  items	Array<Objekt> (min 1, max 100)	Pflicht	Die Briefe des Stapels. Jeder Eintrag trägt seinen eigenen clientOrderId und genau eine Quelle: eine letterId ODER einen inline Brief.
  presetName	string	Optional	Optionales Preset für den ganzen Stapel; pro Eintrag überschreibbar ist nicht vorgesehen.
  stopOnError	boolean	Optional	Bricht den Stapel beim ersten Fehler ab. Standard false.
  dryRun	boolean	Optional	Simuliert den ganzen Stapel: prüft jeden Eintrag, berechnet aber nichts und versendet nichts.

  Fehlercodes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, DAILY_CAP_EXCEEDED, MANDANT_CAP_EXCEEDED, COST_OVER_LIMIT, CONTENT_REJECTED, COUNTRY_NOT_SUPPORTED, LEGAL_PROOF_UNAVAILABLE_FOR_COUNTRY, PRICE_UNAVAILABLE, SANDBOX_DISABLED, IDEMPOTENCY_CONFLICT, DESIGN_NOT_FOUND, DESIGN_RENDER_FAILED, DESIGN_ZONE_VIOLATION

• order_fix_resubmitScope: order:sendkein dryRun

  Korrigiert die Empfängeradresse eines Briefs im Status awaiting_partner_fix und reicht ihn erneut ein. Das setzt voraus, dass die OAuth-Verbindung approval:self_approve trägt. Andernfalls liefert der Aufruf einen Link, über den der Mensch im angemeldeten Portal entscheidet. Der Preis bleibt unverändert.

  Feld	Typ
  orderId	string (uuid)	Pflicht
  recipient	unbekannt	Pflicht	Die korrigierte Empfängeradresse als Einzelfelder oder als { addressId } aus dem Partner-Adressbuch.
  clientOrderId	string	Optional

  Idempotenzschlüssel: clientOrderId (siehe Konventionen).

• document_createScope: order:sendkein dryRun

  Erzeugt aus strukturierten Belegdaten ein fertiges Dokument und legt es als Briefentwurf an: FrankKi rechnet Positionen, Netto, USt-Sätze und Brutto nach, prüft die Pflichtangaben nach § 14 UStG, vergibt auf Wunsch die Belegnummer aus dem Nummernkreis des Kontos und setzt alles im DIN-5008-Layout mit dem Briefdesign des Absenders. Der Entwurf bleibt kostenfrei liegen, bis er versendet wird. Alle Beträge in ganzen Cent. Kompaktes Beispiel: {"document":{"documentType":"rechnung","documentNumber":"RE-2026-014","documentDate":"2026-07-30","leistungszeitraum":{"von":"2026-06-01","bis":"2026-06-30"},"zahlungszielTage":14,"lineItems":[{"description":"Beratung Juni","quantity":4,"unit":"Std","unitPriceCents":12000,"ustRate":19,"lineNetCents":48000}],"totals":{"nettoCents":48000,"ustLines":[{"rate":19,"netCents":48000,"ustCents":9120}],"bruttoCents":57120}},"recipientAddressId":"…"} Nächster Schritt mit der zurückgegebenen letterId: order_send versendet den Brief, approval_submit legt ihn stattdessen einem Menschen zur Freigabe vor, letter_schedule versendet ihn später.

  Feld	Typ
  document	Objekt	Pflicht	Die Belegdaten. Alle Beträge in ganzen Cent. Der Aufruf liefert die Summen mit, FrankKi rechnet sie nach und lehnt Abweichungen ab.
  sequenceScope	Objekt	Optional
  subject	string, max. 200 Zeichen	Optional	Betreff des Briefs. Ohne Angabe setzt FrankKi ihn aus Dokumentart und Belegnummer, z. B. 'Rechnung RE-2026-014'.
  language	de | en	Optional	Standard de.
  recipientAddressId	string (uuid)	Optional	Empfänger aus dem Adressbuch (address_list / mandant_search liefern die id). Entweder das oder recipientAddressInline.
  recipientAddressInline	Objekt	Optional
  mandantennummer	string	Optional	Mandant, dem das Dokument zugeordnet wird. Nur Zuordnung für Liste und Auswertung.
  senderAddressId	string (uuid)	Optional
  senderProfileId	string (uuid)	Optional	Absenderprofil, aus dem die Pflichtangaben (USt-IdNr oder Steuernummer) gelesen werden. Ohne Angabe gilt das Standardprofil.
  designId	string (uuid)	Optional
  reference	Objekt	Optional
  includeSignature	boolean	Optional
  signatureId	string (uuid)	Optional
  clientLetterId	string	Optional	Idempotenzschlüssel für den Briefentwurf.