Die HTTP-Schnittstelle von Zeddly.

Voraussetzung

Sitzung. Ausdrücklich keine Organisation nötig.

Antwort

{
  "user": {
    "id": "66cf…",
    "email": "anna@kanzlei-weber.de",
    "name": "Anna Weber",
    "userRole": "user"
  },
  "organization": {
    "id": "66d0…",
    "name": "Weber & Partner",
    "slug": "weber-partner",
    "createdAt": "2026-08-01T07:12:00.000Z"
  },
  "role": "admin",
  "organizations": [ /* alle Mitgliedschaften */ ]
}

Fehler

• 401Keine gültige Sitzung.

Hinweise

• organization und role sind null, solange das Konto keiner Organisation angehört. Das ist kein Fehler, sondern die Antwort, auf die der Registrierungsablauf wartet.
• user.userRole ist die Plattformrolle (user für jede Kundin, admin nur für Zeddly). role ist die Rolle in dieser einen Organisation. Die beiden sind verschiedene Felder auf verschiedenen Datensätzen und dürfen nie verglichen werden.

Voraussetzung

Sitzung. Ausdrücklich keine Organisation nötig — hier entsteht die erste.

Anfrage

{ "name": "Weber & Partner" }

Antwort

Dasselbe Me-Objekt wie GET /api/me, jetzt mit der neuen Organisation als aktiver.

Fehler

• 400Name kürzer als 2 oder länger als 120 Zeichen.
• 400Für den Namen ließ sich keine freie Kennung finden.
• 401Keine gültige Sitzung.

Hinweise

• Der Name ist nicht eindeutig und wird es nicht: zwei echte Firmen heißen beide „Müller GmbH“. Eindeutig ist der daraus abgeleitete slug.
• Wer anlegt, wird admin dieser Organisation — und nur dieser.

Voraussetzung

Sitzung, plus Mitgliedschaft in der Zielorganisation.

Anfrage

{ "organizationId": "66d0…" }

Antwort

Das Me-Objekt mit der neuen aktiven Organisation.

Fehler

• 400organizationId fehlt oder ist leer.
• 403Das Konto gehört dieser Organisation nicht an.
• 404Es gibt keine Organisation mit dieser ID.

Hinweise

• Die Wahl steht auf der Sitzung, nicht im Client. Jede folgende Anfrage ist auf diese Organisation gefiltert, bis wieder gewechselt wird.

Voraussetzung

Sitzung + Organisation.

Anfrage

?archived=true — archivierte Vorlagen mit auflisten. Ohne den Parameter: nur aktive. Sortiert nach createdAt, neueste zuerst.

Antwort

LetterTemplate[] — siehe „Objekte“.

Fehler

• 401Keine gültige Sitzung.
• 403Das Konto gehört keiner Organisation an.

Voraussetzung

Sitzung + Organisation.

Antwort

Ein LetterTemplate inklusive analysis.

Fehler

• 404Keine Vorlage mit dieser ID in dieser Organisation. Auch bei einer syntaktisch ungültigen ID.

Voraussetzung

Sitzung + Organisation.

Anfrage

Content-Type: multipart/form-data

name=Mandantenschreiben 2026
file=@brief.pdf

Antwort

Das angelegte LetterTemplate, samt analysis und usable.

Fehler

• 400Kein Name, oder länger als 120 Zeichen.
• 400Die Datei ist leer, kein PDF, oder größer als 20 MB.
• 400Das PDF ließ sich nicht lesen oder hat mehr Seiten als verarbeitet werden.

Hinweise

• Der Name wird bewusst nicht aus dem Dateinamen abgeleitet. Brief_final_v4_NEU (2).pdf ist kein Name, den jemand auf einem Bildschirm lesen will.
• Die Antwort enthält bereits das Prüfergebnis. usable: false heißt: aus dieser Vorlage entstehen keine Briefe — warum, steht in analysis.problems.
• Die wichtigste Einzelfrage ist analysis.placeholdersArePaintedWhite. Ist sie false, druckt die Vorlage ihre eigenen Musterdaten unter jede echte Anschrift, und keinem Brief im Lauf sieht man es an.

Voraussetzung

Sitzung + Organisation.

Anfrage

{
  "name": "Mahnung Stufe 2",
  "content": {
    "senderLines": ["Weber & Partner", "Rheinpromenade 10, 40789 Monheim"],
    "place": "Monheim",
    "subject": "Ihre offene Rechnung 4821",
    "salutation": "Guten Tag {{anrede}} {{nachname}},",
    "body": {
      "text": "wir haben Ihre Zahlung bis heute nicht erhalten.",
      "marks": [{ "from": 22, "to": 29, "style": "bold" }]
    },
    "closingPhrase": "Mit freundlichen Grüßen",
    "closingName": "Anna Weber",
    "fontSizePt": 10
  }
}

Antwort

Das angelegte LetterTemplate mit kind: "composed", content und der Messung des erzeugten Korrekturabzugs.

Fehler

• 400Mehr als zwei Absenderzeilen — darunter beginnt der DVF-Sperrbereich.
• 400Leerer Brieftext, oder länger als 20 000 Zeichen.
• 400Eine Formatierung ist leer, rückwärts, oder reicht über das Textende hinaus.
• 400fontSizePt ist nicht 9, 10, 11 oder 12.

Hinweise

• In diesem Rumpf stehen keine Koordinaten, und das ist der Sicherheitsgewinn. Wo Text landet, entscheidet der Briefrahmen, der einmal nach der Schablone gebaut und bei jedem Satz gegen sie geprüft wird. Eine Angabe, die Text in den Sperrbereich setzt, lässt sich hier nicht formulieren.
• Formatierungen sind Bereiche [from, to) über den Text, keine Auszeichnung im String. Grund: {{vorname}} wird je Empfängerin ersetzt und ändert dabei die Länge — die Bereiche wandern mit, **fett** würde verrutschen.
• Die erzeugte PDF-Datei ist ein Korrekturabzug mit Musterdaten. Dass darin Musterwerte sichtbar sind, ist der Zweck eines Abzugs und kein Mangel — anders als bei einer hochgeladenen Vorlage.

Voraussetzung

Sitzung + Organisation.

Anfrage

Derselbe Rumpf wie POST /api/templates/composed.

Antwort

Das aktualisierte LetterTemplate mit frischer Messung.

Fehler

• 400Die Vorlage ist ein hochgeladenes PDF und lässt sich so nicht bearbeiten.
• 400Die Vorlage ist archiviert.
• 404Keine Vorlage mit dieser ID in dieser Organisation.

Hinweise

• PUT und nicht PATCH: der Rumpf ist der ganze Brief. Ein Teilupdate hieße, zwei Fassungen eines Briefes zu verschmelzen und das Ergebnis zu drucken.

Voraussetzung

Sitzung + Organisation.

Antwort

application/pdf, mit Content-Disposition: inline.

Fehler

• 404Keine Vorlage mit dieser ID, oder zu ihr gibt es keine Datei.

Hinweise

• Es gibt keine vorsignierten Links. Eine Datei kommt durch diesen Endpunkt, mit Sitzung und Organisationsfilter im Weg — ein signierter Link wäre ein Inhaberschlüssel auf einen Brief an eine echte Person und überlebt in Verlauf und Referer.

Voraussetzung

Sitzung + Organisation.

Antwort

Das LetterTemplate mit gesetztem archivedAt.

Fehler

• 404Keine Vorlage mit dieser ID in dieser Organisation.

Hinweise

• Archivieren löscht nichts. Kampagnen, die diese Vorlage benutzt haben, verweisen weiter auf sie.
• Antwortet 200 und nicht 201: hier entsteht nichts, es wird ein Datum auf einem vorhandenen Datensatz gesetzt.

Voraussetzung

Sitzung + Organisation.

Antwort

Campaign[] — siehe „Objekte“.

Fehler

• 401Keine gültige Sitzung.
• 403Das Konto gehört keiner Organisation an.

Hinweise

• counts wird bei jeder Abfrage aus den Briefen gezählt und nicht mitgeführt. Damit kann es nicht auseinanderlaufen — und es ist der Grund, die Liste nicht in einer Schleife abzufragen.

Voraussetzung

Sitzung + Organisation.

Antwort

Eine Campaign.

Fehler

• 404Keine Kampagne mit diesem Code in dieser Organisation.

Hinweise

• Adressiert wird über den code, nicht über die id. Ein Versand = ein Code. Ein anderer Code heißt: ein anderer Brief — und die Dublettenprüfung zählt je Code.

Voraussetzung

Sitzung + Organisation + Rolle admin.

Anfrage

{ "allowDuplicates": false }

Antwort

{ "queued": 418 }

Fehler

• 403Die Rolle in dieser Organisation ist marketing oder viewer.
• 404Keine Kampagne mit diesem Code in dieser Organisation.
• 409Zwei Entwürfe teilen sich eine Anschrift. code: "DUPLICATE_ADDRESSES", details listet die Adressschlüssel.

Hinweise

• Das ist der einzige schreibende Aufruf, den ein Client auf einen Brief machen darf. Er setzt Entwürfe auf queued. Jeden weiteren Übergang — sent, failed, skipped — macht ausschließlich der Versandprozess. Zwei Schreiber auf einem Brief sind nur so lange harmlos, wie diese Zeile hält.
• allowDuplicates: true übergeht die Dublettenprüfung. Das ist die Entscheidung eines Menschen vor dem Bildschirm und gehört in keinen automatisierten Aufruf: ein eingelieferter Brief lässt sich nicht zurückholen. Es gibt bei der Deutschen Post keinen Endpunkt dafür — im Ernstfall waren es zwei identische Briefe an eine Adresse, und das ist schon passiert.
• Antwortet 200 und nicht 201: es entsteht nichts, vorhandene Briefe wechseln den Zustand.

Voraussetzung

Keine.

Antwort

{ "ok": true, "db": 1 }

Fehler

• 503Die Datenbank ist nicht erreichbar. ok: false, db ist der Verbindungszustand.

Hinweise

• 503 ist hier eine Aussage über die Bereitschaft, kein Fehler — die Antwort hat denselben Rumpf wie im Erfolgsfall.