Briefentwurf anlegen
letter_create_draftLegt einen Briefentwurf an: erstellt eine Vorschau-PDF im hinterlegten Briefdesign (nur der Brieftext), speichert den Entwurf und liefert eine Seitenzahl, einen Vorschau-Link (24 Stunden gültig) und eine unverbindliche Kostenvorschau. Der Entwurf bleibt kostenfrei liegen, bis du ihn versendest. Der Brieftext ist entweder content (Fliesstext) ODER blocks (strukturiert: Tabellen, Ueberschriften, 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}]}]} Volle Referenz inkl. styleDefs und Limits: MCP-Ressource frankki://blocks-guide. Die ersten Seiten kommen als Bild zurück: sieh sie dir an, bevor du versendest, und prüfe Betreff, Anschrift im Adressfenster, Absender, Datum und Umbrüche. Gemeldete Auffälligkeiten stehen in warnings. Findest du einen Fehler, korrigiere ihn und lege den Entwurf neu an, solange er noch Entwurf ist: gedruckt geht der Brief endgültig raus. 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. EN: Creates a letter draft: produces a preview PDF in the stored letter design (letter body only), stores the draft and returns a page count, a preview link (valid for 24 hours) and a non-binding cost estimate. The draft stays free of charge until you send it. The body is either content (plain text) OR blocks (structured: tables, headings, totals lines), exactly one of the two. Compact blocks example: {"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}]}]} Full reference incl. styleDefs and limits: MCP resource frankki://blocks-guide. The first pages come back as images: look at them before sending and check the subject, the address inside the address window, sender, date and line breaks. Reported findings are in warnings. If you find a defect, fix it and create the draft again while it is still a draft: once printed, the letter is out for good. Next step with the returned letterId: letter_preview shows the draft as an image to refine it, order_send sends the draft, letter_schedule sends it at a later time.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| blocks | No | Strukturierter Briefinhalt als typisierte Bloecke (Alternative zu content, nie beides). Limits: 200 Bloecke, 100 Zeilen/Tabelle, 20 Spalten, 2000 Zeichen/Zelle, 10 Bilder, 262144 Bytes. EN: structured letter content as typed blocks (alternative to content, never both). Jeder Block braucht type; erlaubte Typen: paragraph, heading, keyValue, checkboxRow, fillLine, table, totals, columns, box, image, spacer, pageBreak. Die vollstaendige Feldreferenz liegt in der MCP-Ressource frankki://blocks-guide. EN: every block needs type; read frankki://blocks-guide for the complete field reference. | |
| content | No | Brieftext als Fliesstext. Entweder content ODER blocks, nie beides. EN: letter body as plain text. Either content OR blocks, never both. | |
| subject | Yes | ||
| designId | No | Ein gespeichertes Briefdesign fuer diesen Brief verwenden. Es wird bereits in der Vorschau-PDF gerendert und am Entwurf gespeichert, sodass ein spaeterer Versand ueber die letterId es uebernimmt (ausser der Versand nennt selbst ein Design). Ohne Angabe gilt das Standard-Design des Absenderprofils, in der Vorschau wie beim Versand. EN: Use a saved letter design for this letter. It is already rendered into the preview PDF and stored on the draft so a later send by letterId inherits it (unless the send names its own design). If omitted, the sender profile default design applies, in the preview as well as on send. | |
| language | No | Standard de. EN: Defaults to de. | |
| reasoning | No | ||
| reference | No | Werte fuer diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie fuellen den Infoblock und den Barcode. EN: Per-letter values (Vorgangsnummer, your reference, customer number, QR parameters ...). They fill the info block and the barcode. | |
| styleDefs | No | Benannte Stile fuer das ganze Dokument (max. 24). Bloecke referenzieren sie ueber style. EN: named document styles (max 24); blocks reference them via style. Vollstaendige Stilfelder: frankki://blocks-guide. EN: complete style fields: frankki://blocks-guide. | |
| presetName | No | ||
| signatureId | No | Eine bestimmte gespeicherte Unterschrift verwenden statt der zuerst hinterlegten. EN: Use a specific stored signature instead of the first one on file. | |
| clientLetterId | No | Idempotenzschluessel. Ein erneuter Aufruf mit demselben Wert UND derselben Nutzlast liefert denselben Entwurf, statt einen zweiten anzulegen. Fuer einen anderen Brief brauchst du einen neuen Schluessel: derselbe Schluessel mit anderem Inhalt wird mit IDEMPOTENCY_CONFLICT abgelehnt, damit du keinen Brief fuer angelegt haeltst, den es nicht gibt. EN: Idempotency key. A repeat call with the same value AND the same payload returns the same draft instead of creating a second one. A different letter needs a new key: the same key with different content is refused with IDEMPOTENCY_CONFLICT, so you never believe a letter exists that does not. | |
| senderAddressId | No | ||
| senderProfileId | No | Absenderprofil, mit dem spaeter versendet wird. Fuer die Vorschau zaehlt daraus nur das Standard-Briefdesign. EN: Sender profile the letter will later be sent with. For the preview only its default letter design is used. | |
| includeSignature | No | Hinterlegte Unterschrift unter den Brieftext setzen. Standard aus, wie beim Versand. EN: Place the stored signature under the letter text. Off by default, same as on send. | |
| recipientAddressInline | No |