{"openapi":"3.1.0","info":{"title":"Versendo API","version":"1.0.0","description":"Echte Briefe per Deutscher Post aus Daten erstellen. Test-Schlüssel (vs_test_…) verschicken nie echt."},"servers":[{"url":"https://versendo.de"}],"components":{"securitySchemes":{"schluessel":{"type":"http","scheme":"bearer","description":"API-Schlüssel vs_test_…"}},"schemas":{"BriefEingabe":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"absender":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":70,"description":"Vollständiger Name oder Firma (Absender)"},"zusatz":{"description":"Optional: zweite Zeile, z. B. 'z. Hd. Frau Müller', Abteilung oder c/o","type":"string","maxLength":70},"strasse":{"type":"string","minLength":3,"maxLength":70,"description":"Straße und Hausnummer oder Postfach"},"plz":{"type":"string","pattern":"^\\d{5}$","description":"Postleitzahl, 5 Ziffern (nur Deutschland)"},"ort":{"type":"string","minLength":2,"maxLength":50,"description":"Ort"}},"required":["name","strasse","plz","ort"],"description":"Wer den Brief verschickt. Niemals erfinden. Fehlende Angaben beim Nutzer erfragen."},"empfaenger":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":70,"description":"Vollständiger Name oder Firma (Empfänger)"},"zusatz":{"description":"Optional: zweite Zeile, z. B. 'z. Hd. Frau Müller', Abteilung oder c/o","type":"string","maxLength":70},"strasse":{"type":"string","minLength":3,"maxLength":70,"description":"Straße und Hausnummer oder Postfach"},"plz":{"type":"string","pattern":"^\\d{5}$","description":"Postleitzahl, 5 Ziffern (nur Deutschland)"},"ort":{"type":"string","minLength":2,"maxLength":50,"description":"Ort"}},"required":["name","strasse","plz","ort"],"description":"Empfängeranschrift. Niemals erfinden. Wenn du sie recherchiert hast, lass sie den Nutzer vorher bestätigen."},"betreff":{"type":"string","minLength":3,"maxLength":110,"description":"Betreffzeile, ohne das Wort 'Betreff'"},"text":{"type":"string","minLength":20,"maxLength":12000,"description":"Brieftext MIT Anrede (z. B. 'Sehr geehrte Damen und Herren,'), aber OHNE Grußformel und Unterschrift. Absätze durch eine Leerzeile trennen."},"grussformel":{"description":"Standard: 'Mit freundlichen Grüßen'","type":"string","maxLength":50},"unterzeichner":{"description":"Name unter der Grußformel. Standard: Name des Absenders","type":"string","maxLength":70},"referenzen":{"description":"Optionale Angaben rechts oben, z. B. Kundennummer oder Vertragsnummer","maxItems":4,"type":"array","items":{"type":"object","properties":{"bezeichnung":{"type":"string","minLength":1,"maxLength":25},"wert":{"type":"string","minLength":1,"maxLength":35}},"required":["bezeichnung","wert"]}},"briefart":{"type":"string","enum":["kuendigung_arbeitsverhaeltnis","kuendigung_mietverhaeltnis","aufhebungsvertrag","kuendigung_vertrag","vereinsaustritt","widerspruch_behoerde","widerspruch_sonstiges","mahnung_oder_zahlungserinnerung","reklamation","sonstiges"],"description":"Art des Schreibens. Entscheidet über die Prüfung von Formvorschriften. Wahrheitsgemäß angeben."},"einschreiben":{"default":"nein","description":"'einwurf' = Einwurf-Einschreiben mit Zustellnachweis. Für Kündigungen und Fristsachen empfehlen.","type":"string","enum":["nein","einwurf"]}},"required":["absender","empfaenger","betreff","text","briefart"]},"Brief":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["entwurf","gesperrt","bezahlt","an_druckerei","versendet","fehlgeschlagen"]},"modus":{"type":"string","enum":["test","live"]},"seiten":{"type":"integer"},"preis_cent":{"type":"integer"},"einschreiben":{"type":"string"},"erstellt_am":{"type":"string","format":"date-time"},"pdf_url":{"type":["string","null"]},"versand_referenz":{"type":["string","null"]},"hinweise":{"type":"array","items":{"type":"string"}},"geloescht_am":{"type":["string","null"]}}},"Fehler":{"type":"object","properties":{"fehler":{"type":"object","properties":{"code":{"type":"string"},"meldung":{"type":"string"}},"required":["code","meldung"]}}}}},"paths":{"/v1/briefe":{"post":{"summary":"Brief erstellen","security":[{"schluessel":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":100},"description":"Gleicher Key = gleicher Brief, kein Doppelversand."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefEingabe"}}}},"responses":{"200":{"description":"Wiederholung mit gleichem Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brief"}}}},"201":{"description":"Erstellt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brief"}}}},"400":{"description":"Eingabe ungültig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"401":{"description":"Schlüssel fehlt oder unbekannt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"422":{"description":"Schriftform erforderlich oder Brief ungültig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"429":{"description":"Tageslimit erreicht","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}}},"/v1/briefe/{id}":{"get":{"summary":"Status eines Briefs","security":[{"schluessel":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brief"}}}},"404":{"description":"Nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}}},"/v1/preise":{"get":{"summary":"Preise","responses":{"200":{"description":"Preisliste"}}}},"/api/schluessel":{"post":{"summary":"Test-Schlüssel erzeugen","responses":{"201":{"description":"Neuer Schlüssel (nur einmal sichtbar)"}}}}}}