{"openapi":"3.1.0","info":{"title":"Tamgara API","version":"1.0.0","description":"PDF-Rechtsvorlagen (Kaufvertrag, Kündigung, Vollmacht u. a.) in vielen Sprachen und Rechtsräumen suchen, Feld-Schema abrufen und ausgefüllt + signiert als PDF erhalten. Kostenlos, ohne Konto. Zusätzlich Versand-Flows: Fax, Postbrief (beide bezahlt via Stripe-Link) und mehrparteiige E-Signatur."},"servers":[{"url":"https://api.tamgara.com/api/v1","description":"Tamgara API v1"}],"paths":{"/tools/fax_countries":{"post":{"operationId":"fax_countries","summary":"Unterstützte Fax-Zielländer + Hinweise zur E.164-Nummer.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/fax_ping":{"post":{"operationId":"fax_ping","summary":"Prüft, ob Faxversand verfügbar ist und ob er bezahlt (Stripe) läuft.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/fax_quote":{"post":{"operationId":"fax_quote","summary":"Preis für einen Faxversand. Seitenzahl aus pdfBase64 abgeleitet, wenn nicht angegeben.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdfBase64":{"type":"string","description":"Das zu faxende PDF (z. B. aus fill_template)."},"pages":{"type":"integer","description":"Seitenzahl (optional; sonst aus PDF)."},"to":{"type":"string","description":"Zielnummer E.164 (optional, für Zonenpreis)."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/fax_create_checkout":{"post":{"operationId":"fax_create_checkout","summary":"Startet den bezahlten Faxversand: liefert eine Stripe-Checkout-URL. Der MENSCH bezahlt über diese URL; danach fax_confirm mit der job_id. (Kein kostenloser Direktversand über die KI.)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"Zielnummer in E.164, z. B. +4976339202117."},"pdfBase64":{"type":"string","description":"Das zu faxende PDF."},"filename":{"type":"string","description":"Dateiname (optional)."},"pages":{"type":"integer","description":"Seitenzahl (optional)."}},"required":["to","pdfBase64"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/fax_confirm":{"post":{"operationId":"fax_confirm","summary":"Nach erfolgter Zahlung: Fax in die Warteschlange geben. Braucht die job_id aus fax_create_checkout.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"job_id aus fax_create_checkout."}},"required":["jobId"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/fax_status":{"post":{"operationId":"fax_status","summary":"Zustellstatus eines Fax (queued/sending/success/failed) per id.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Fax-id."}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/brief_ping":{"post":{"operationId":"brief_ping","summary":"Prüft, ob Briefversand (Post via LetterXpress) verfügbar/bezahlt ist.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/brief_quote":{"post":{"operationId":"brief_quote","summary":"Preis für einen Postbrief (Standard oder Einschreiben). Länder: DE/AT/CH.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdfBase64":{"type":"string","description":"Das zu versendende PDF."},"pages":{"type":"integer","description":"Seitenzahl (optional; sonst aus PDF)."},"registered":{"type":"boolean","description":"Einwurf-Einschreiben statt Standard."},"country":{"type":"string","description":"Zielland: DE | AT | CH (Default DE)."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/brief_create_checkout":{"post":{"operationId":"brief_create_checkout","summary":"Startet den bezahlten Briefversand: liefert eine Stripe-Checkout-URL. Der MENSCH bezahlt; danach brief_confirm mit der job_id. (Kein kostenloser Direktversand über die KI.)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdfBase64":{"type":"string","description":"Das zu versendende PDF."},"recipient":{"type":"string","description":"Anzeigename des Empfängers (für Beleg)."},"country":{"type":"string","description":"Zielland: DE | AT | CH."},"registered":{"type":"boolean","description":"Einwurf-Einschreiben."},"filename":{"type":"string","description":"Dateiname (optional)."},"pages":{"type":"integer","description":"Seitenzahl (optional)."}},"required":["pdfBase64","recipient"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/brief_confirm":{"post":{"operationId":"brief_confirm","summary":"Nach Zahlung: Brief einreichen. Braucht die job_id aus brief_create_checkout.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"job_id aus brief_create_checkout."}},"required":["jobId"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/brief_status":{"post":{"operationId":"brief_status","summary":"Status/Tracking eines Briefs per id.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Brief-id."}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/brief_cancel":{"post":{"operationId":"brief_cancel","summary":"Storniert einen Brief im 15-Minuten-Fenster von LetterXpress.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Brief-id."}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/envelope_create":{"post":{"operationId":"envelope_create","summary":"Sendet ein PDF zur mehrparteiigen elektronischen Signatur (DocuSign-Stil). Liefert die Vorgangs-id, einen ownerKey (geheim halten!) und pro Empfänger einen Signier-Link. fields platzieren Signatur-/Text-/Datum-/Checkbox-Felder per Ratio (0..1, y von oben). Emails an Empfänger nur über den zurückgegebenen ownerKey.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ownerName":{"type":"string","description":"Name des Absenders/Erstellers."},"docName":{"type":"string","description":"Dokumentname, z. B. \"Mietvertrag.pdf\"."},"pdfBase64":{"type":"string","description":"Das zu signierende PDF (z. B. aus fill_template)."},"message":{"type":"string","description":"Begleitnachricht an die Empfänger (optional)."},"expiresDays":{"type":"integer","description":"Ablauf in Tagen (0 = kein Ablauf)."},"isPublic":{"type":"boolean","description":"Öffentlicher Signier-Link statt fester Empfänger."},"recipients":{"type":"array","description":"Empfänger (bei isPublic leer).","items":{"type":"object","properties":{"name":{"type":"string","description":"Name des Unterzeichners."},"email":{"type":"string","description":"E-Mail (optional; für Einladung)."},"order":{"type":"integer","description":"Reihenfolge (optional)."},"lang":{"type":"string","description":"Sprache der Einladung: de | en."}},"required":["name"],"additionalProperties":false}},"fields":{"type":"array","description":"Feld-Platzierungen.","items":{"type":"object","properties":{"type":{"type":"string","enum":["signature","initials","text","date","checkbox"]},"label":{"type":"string","description":"Feldbeschriftung."},"recipient":{"type":"integer","description":"Index des Empfängers (0-basiert)."},"pageIndex":{"type":"integer","description":"Seitenindex (0-basiert)."},"xRatio":{"type":"number","description":"X-Position 0..1 (Mitte)."},"yRatio":{"type":"number","description":"Y-Position 0..1 von oben (Mitte)."}},"required":["type","recipient","pageIndex","xRatio","yRatio"],"additionalProperties":false}}},"required":["ownerName","docName","pdfBase64"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/envelope_status":{"post":{"operationId":"envelope_status","summary":"Status eines Signier-Vorgangs (wer hat gesehen/unterschrieben) per id + ownerKey.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Vorgangs-id."},"ownerKey":{"type":"string","description":"Der bei create erhaltene ownerKey."},"withInputs":{"type":"boolean","description":"Eingaben mitliefern."}},"required":["id","ownerKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/envelope_send_invite":{"post":{"operationId":"envelope_send_invite","summary":"Verschickt (erneut) die Signier-Einladung per E-Mail an einen Empfänger. Nur mit ownerKey.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Vorgangs-id."},"ownerKey":{"type":"string","description":"ownerKey."},"recipient":{"type":"integer","description":"Empfänger-Index (0-basiert)."},"email":{"type":"string","description":"Ziel-E-Mail."}},"required":["id","ownerKey","recipient","email"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/envelope_void":{"post":{"operationId":"envelope_void","summary":"Storniert/annulliert einen Signier-Vorgang. Nur mit ownerKey.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Vorgangs-id."},"ownerKey":{"type":"string","description":"ownerKey."}},"required":["id","ownerKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/envelope_upload_final":{"post":{"operationId":"envelope_upload_final","summary":"Lädt das fertige (z. B. lokal signierte) PDF für einen Vorgang hoch. Nur mit ownerKey.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Vorgangs-id."},"ownerKey":{"type":"string","description":"ownerKey."},"pdfBase64":{"type":"string","description":"Fertiges PDF."}},"required":["id","ownerKey","pdfBase64"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/inspect_pdf":{"post":{"operationId":"inspect_pdf","summary":"Ein BELIEBIGES PDF (base64) analysieren: Seitenzahl/-größen, ausfüllbare Formularfelder (Name, Typ, Label, Optionen), Signaturfelder und Unterschrifts-Positionen. Grundlage zum Ausfüllen fremder PDFs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdfBase64":{"type":"string","description":"Das PDF als base64."}},"required":["pdfBase64"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/fill_pdf":{"post":{"operationId":"fill_pdf","summary":"Ein BELIEBIGES (nicht-Katalog-)PDF ausfüllen und optional signieren → fertiges PDF (base64). answers = Feldname→Wert (aus inspect_pdf). Unterschrift wird in erkannte Signaturfelder gesetzt oder per manualPlacement platziert. lang (optional) wählt die Schrift für nicht-lateinische Eingaben (ar/zh/hi/…).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdfBase64":{"type":"string","description":"Das auszufüllende PDF (base64)."},"answers":{"type":"object","description":"Feldname → Wert (String/Boolean).","additionalProperties":true},"signaturePngDataUrl":{"type":"string","description":"Unterschrift als PNG data:-URL (optional)."},"lang":{"type":"string","description":"Sprachhinweis für die Schrift (z. B. ar, zh, hi) — optional."},"manualPlacement":{"type":"object","properties":{"pageIndex":{"type":"integer","description":"Seitenindex (0-basiert)."},"xRatio":{"type":"number","description":"X 0..1."},"yRatio":{"type":"number","description":"Y 0..1 von oben."}},"required":[],"additionalProperties":false},"extraText":{"type":"object","properties":{"text":{"type":"string","description":"Zusatztext (z. B. Ort, Datum)."},"placement":{"type":"object","properties":{"pageIndex":{"type":"integer","description":"Seitenindex."},"xRatio":{"type":"number","description":"X 0..1."},"yRatio":{"type":"number","description":"Y 0..1 von oben."}},"required":[],"additionalProperties":false}},"required":[],"additionalProperties":false},"filename":{"type":"string","description":"Dateiname (optional)."}},"required":["pdfBase64"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/pdf_from_images":{"post":{"operationId":"pdf_from_images","summary":"Aus einem oder mehreren Bildern (base64 PNG/JPEG) ein PDF bauen — ein Bild pro Seite (Foto/Scan → PDF).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"images":{"type":"array","items":{"type":"string"},"description":"base64-Bilder (mit oder ohne data:-Präfix)."},"filename":{"type":"string","description":"Dateiname (optional)."}},"required":["images"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/add_cover_page":{"post":{"operationId":"add_cover_page","summary":"Stellt einem PDF ein DIN-5008-Adressblatt voran (für den Postversand). recipient = {name,street,zip,city,country}.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdfBase64":{"type":"string","description":"Das PDF (base64)."},"recipient":{"type":"object","properties":{"name":{"type":"string","description":"Empfängername."},"street":{"type":"string","description":"Straße + Nr."},"zip":{"type":"string","description":"PLZ."},"city":{"type":"string","description":"Ort."},"country":{"type":"string","description":"ISO-2, z. B. DE/AT/CH."}},"required":["name","street","zip","city"],"additionalProperties":false},"senderLine":{"type":"string","description":"Einzeilige Rücksendeangabe über dem Adressblock (optional)."},"filename":{"type":"string","description":"Dateiname (optional)."}},"required":["pdfBase64","recipient"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/tools/apply_scan_answers":{"post":{"operationId":"apply_scan_answers","summary":"Befüllt erkannte Felder eines gescannten (nicht-AcroForm-)PDFs: Text auf Schreiblinien, X in Checkboxen — per Ratio-Positionen (z. B. aus einer Feld-Erkennung).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdfBase64":{"type":"string","description":"Das gescannte PDF (base64)."},"fields":{"type":"array","description":"Erkannte Felder.","items":{"type":"object","properties":{"id":{"type":"string","description":"Feld-id (Schlüssel in values)."},"type":{"type":"string","enum":["line","checkbox","signature"]},"pageIndex":{"type":"integer","description":"Seitenindex (0-basiert)."},"xStartRatio":{"type":"number","description":"X-Start 0..1."},"xEndRatio":{"type":"number","description":"X-Ende 0..1."},"yRatio":{"type":"number","description":"Y 0..1 von oben (Basislinie/Mitte)."}},"required":["id","type","pageIndex","xStartRatio","xEndRatio","yRatio"],"additionalProperties":false}},"values":{"type":"object","description":"Feld-id → Wert (Text; \"true\" für Checkbox).","additionalProperties":true},"lang":{"type":"string","description":"Sprachhinweis für die Schrift (optional)."},"filename":{"type":"string","description":"Dateiname (optional)."}},"required":["pdfBase64","fields","values"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Fehler / ungültige Eingabe"}}}},"/info":{"get":{"operationId":"getInfo","summary":"Überblick","responses":{"200":{"description":"OK"}}}},"/languages":{"get":{"operationId":"listLanguages","summary":"Unterstützte Sprachen","responses":{"200":{"description":"OK"}}}},"/locales":{"get":{"operationId":"listLocales","summary":"Locales (Sprache×Land)","responses":{"200":{"description":"OK"}}}},"/categories":{"get":{"operationId":"listCategories","summary":"Kategorien","responses":{"200":{"description":"OK"}}}},"/templates":{"get":{"operationId":"searchTemplates","summary":"Vorlagen suchen","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string"},"description":"Freitext."},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Basissprache, z. B. de/en/ar."},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Land ISO-2, z. B. DE/AT/EG."},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Kategorie."},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"Max. Treffer (1–200)."}],"responses":{"200":{"description":"Trefferliste","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"templates":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"id":{"type":"string"},"lang":{"type":"string"},"rtl":{"type":"boolean"},"title":{"type":"string"},"subtitle":{"type":"string"},"emoji":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"blankPdfUrl":{"type":"string"},"fillWebUrl":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/templates/{slug}":{"get":{"operationId":"getTemplate","summary":"Vorlagen-Details + Feld-Schema","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Land ISO-2 für den Rechtsraum."}],"responses":{"200":{"description":"Details","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"slug":{"type":"string"},"id":{"type":"string"},"lang":{"type":"string"},"rtl":{"type":"boolean"},"title":{"type":"string"},"subtitle":{"type":"string"},"emoji":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"blankPdfUrl":{"type":"string"},"fillWebUrl":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}}}},{"type":"object","properties":{"pageCount":{"type":"integer"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"AcroForm-Feldname (sprachübergreifend konstant)."},"label":{"type":"string"},"kind":{"type":"string","enum":["text","multiline","date","checkbox","radio","dropdown"]},"options":{"type":"array","items":{"type":"string"}},"maxLength":{"type":"integer"}}}}}}]}}}},"404":{"description":"Nicht gefunden"}}}},"/templates/{slug}/fill":{"post":{"operationId":"fillTemplate","summary":"Vorlage ausfüllen + optional signieren → PDF (base64)","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"answers":{"type":"object","additionalProperties":true,"description":"Feldname → Wert (String/Boolean)."},"signaturePngDataUrl":{"type":"string","description":"Unterschrift als PNG data:-URL (optional)."},"country":{"type":"string","description":"Land ISO-2 (optional)."}}}}}},"responses":{"200":{"description":"Fertiges PDF","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"pdfBase64":{"type":"string","description":"Das fertige PDF, base64-kodiert."},"signed":{"type":"boolean"}}}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Nicht gefunden"}}}},"/providers":{"get":{"operationId":"listProviders","summary":"Kündigungs-Anbieter (de/at/ch)","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"de | at | ch."},{"name":"query","in":"query","required":false,"schema":{"type":"string"},"description":"Freitext."},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"Max. Treffer."}],"responses":{"200":{"description":"OK"}}}},"/providers/{country}/{id}":{"get":{"operationId":"getProvider","summary":"Ein Anbieter","parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Nicht gefunden"}}}}}}