Briefdesign

1. 1

   Was ist ein Briefdesign?

   Ein Briefdesign ist dein wiederverwendbares Briefpapier: ein Briefkopf mit Logo (oben, rechts neben dem Absender, oder als vollflaechiger Hintergrund, der auch den Server-Absenderblock ersetzen kann), ein DIN-5008-Infoblock rechts oben (Ihr Zeichen, Unser Zeichen, Vorgangsnummer, Kundennummer, Datum und bis zu vier eigene Felder), eine klassische Fusszeile mit 1 bis 4 Spalten, ein zur Kompositionszeit erzeugter QR- oder Code128-Barcode, sowie Falz- und Lochmarken im linken Rand. Du speicherst ein Briefdesign einmal pro Partnerkonto unter einem Namen und referenzierst es danach per designId in jedem Versand. Jedes Element wird gegen die DIN-5008- und Pingen/LetterXPress-Zustellzonen (Adress- fenster, Freimachungszone, Brieftext-Bereich) geprueft, bevor es je in einem Versand verwendet wird, ein Design kann die Zustellung also nie versehentlich gefaehrden.

2. 2

   Design speichern (letter_design_save)

   letter_design_save nimmt einen Namen und das komplette Design-JSON entgegen und prueft beides sofort: die Feldgrenzen (Zod-Schema) und die Zustellzonen (z. B. darf der Infoblock nicht ins Adressfenster ragen). Ein ungueltiges Design wird mit DESIGN_ZONE_VIOLATION und einer genauen violations-Liste abgelehnt, bevor es je gespeichert wird. Ohne designId wird per Name angelegt oder ueberschrieben, mit designId aktualisierst du ein bestehendes Design. Die Antwort liefert designId und einen stabilen designHash, der spaeter jeden Auftrag, der dieses Design nutzte, nachvollziehbar macht.

   letter_design_save
   {
     "name": "Kanzlei-Standard",
     "design": {
       "schemaVersion": 1,
       "header": {
         "letterheadId": "7e2a1c9d-4f3b-4a12-9c8e-1a2b3c4d5e6f",
         "placement": "top",
         "widthMm": 60,
         "heightMm": 20,
         "offsetYMm": 8
       },
       "infoblock": {
         "enabled": true,
         "rows": [
           {
             "key": "unser_zeichen",
             "label": "Unser Zeichen",
             "staticValue": "AB-2026"
           },
           {
             "key": "vorgangsnummer",
             "label": "Vorgang",
             "staticValue": null
           },
           {
             "key": "datum",
             "label": "Datum",
             "staticValue": null
           }
         ]
       },
       "footer": {
         "enabled": true,
         "scope": "first-page",
         "columns": [
           [
             "Kanzlei Mueller",
             "Musterstr. 1",
             "12345 Musterstadt"
           ],
           [
             "Tel 030 1234",
             "info@kanzlei-mueller.de"
           ]
         ]
       },
       "barcode": {
         "enabled": true,
         "type": "qr",
         "placement": "infoblock",
         "payloadTemplate": "https://portal.kanzlei.de/v/{{vorgangsnummer}}"
       },
       "falzmarken": {
         "enabled": true
       }
     }
   }

3. 3

   Vorschau (letter_design_preview)

   Bevor du ein Design einsetzt, siehst du es dir an: letter_design_preview komponiert eine Beispielseite mit deinem Design (gespeichert per designId oder inline noch nicht gespeichert) und liefert einen kurzlebigen Vorschau-Link (15 Minuten gueltig). Es wird nichts berechnet und nichts versendet, kein Auftrag entsteht. Uebergib optional reference mit Beispielwerten, damit Infoblock und Barcode genauso aussehen wie im echten Brief.

   letter_design_preview
   {
     "designId": "<designId aus letter_design_save>",
     "reference": {
       "vorgangsnummer": "2026-0042"
     }
   }

4. 4

   Senden mit Vorgangsnummer (order_send mit designId + reference)

   Auf order_send (und order_send_batch, letter_draft) gibst du designId und reference an. designId waehlt das Briefdesign fuer genau diesen Brief, ohne Angabe gilt das Standard-Design des Absender- profils, sonst keins. reference liefert die Werte, die deine Infoblock-Zeilen und dein Barcode-Payload fuer diesen einen Brief brauchen (z. B. vorgangsnummer, ihrZeichen, kundennummer, oder ein eigener Wert unter values). Fehlt ein Wert, den eine Zeile oder der Barcode-Platzhalter zwingend braucht, bricht der Versand VOR jeder Belastung ab, damit nie ein Brief mit leerem Vorgangsnummer-Feld oder einem toten QR-Code verschickt wird.

   order_send
   {
     "clientOrderId": "einspruch-schmidt-2026-07-05",
     "subject": "Einspruch gegen Steuerbescheid vom 15.05.2026",
     "content": "Sehr geehrte Damen und Herren, ...",
     "recipientCompany": "Finanzamt Muenchen-Land",
     "recipientStreet": "Postfach 12 52",
     "recipientZip": "80292",
     "recipientCity": "Muenchen",
     "recipientCountry": "DE",
     "designId": "<designId aus letter_design_save>",
     "reference": {
       "vorgangsnummer": "2026-0042"
     }
   }

5. 5

   Fehlerbehandlung

   Drei neue Fehlercodes gehoeren zum Briefdesign, alle agent-fixable (aus der Antwort allein behebbar): DESIGN_NOT_FOUND (404) bedeutet, die designId existiert nicht oder gehoert nicht zu deinem Konto, pruefe die ID oder liste deine Designs mit letter_design_list. DESIGN_RENDER_FAILED (422) bedeutet, ein Wert fuer den Infoblock oder Barcode fehlt, liefere den genannten Wert in reference nach. DESIGN_ZONE_VIOLATION (422) bedeutet, eine Design-Box verletzt eine Zustellzone, passe die genannte Position/Groesse laut violations an. Die vollstaendige Beschreibung jedes Codes steht im Fehler- katalog, die Feldreferenz jedes Tools in der Tool-Referenz.

Tool-Referenz ansehen →Fehlerkatalog ansehen →