API-Referenz

Public Delivery API — Endpunkte, Parameter und Header

Eine kompakte, lesbare Referenz der Public Delivery API: drei read-only GET-Endpunkte liefern bereits veröffentlichte Rechtstexte als JSON, HTML-Fragment oder PDF. Unten steht zusätzlich die vollständige OpenAPI-3.1-Spezifikation interaktiv im Browser.

openapi.json herunterladenIdentische Spec wie die interaktive Referenz — als statische Datei.

Überblick

Read-only Delivery veröffentlichter Rechtstexte

Die Public Delivery API ist die read-only Schnittstelle, über die bereits veröffentlichte Rechtstexte abgerufen und in Websites, SaaS-Apps, Shops und transaktionale E-Mails eingebunden werden. Sie liefert ausschließlich freigegebene, live geschaltete Fassungen — Schreibvorgänge und unveröffentlichte Entwürfe sind über sie nicht erreichbar. Jeder Abruf adressiert eine Site und einen Dokumenttyp und gibt das Artefakt als JSON-Hülle, HTML-Fragment oder PDF zurück.

Formate

Dieselbe veröffentlichte Version steht in drei Artefaktformen bereit:

JSON: Strukturierte Hülle mit Abschnitten, typisierten Blöcken und Metadaten — für eigene Template- und Rendering-Logik.
HTML-Fragment: Sanitisiertes HTML zum direkten Einbetten in Seiten, App-Footer, Checkout-Schritte oder E-Mails.
PDF-Artefakt: Freigegebene Version als PDF zum Archivieren oder als Anhang in Bestell- und Vertragsbestätigungen.

Endpoint-Gruppen

Drei GET-Endpunkte über einen gemeinsamen Pfad. {siteID} adressiert die Site, {typeCode} den Dokumenttyp (z. B. privacy, terms, imprint).

GET/v1/delivery/sites/{siteID}/documents/{typeCode}
JSON-Hülle
Live-Dokument als strukturierte JSON-Hülle mit Abschnitten, Blöcken und Versions-Metadaten.
GET/v1/delivery/sites/{siteID}/documents/{typeCode}/html
HTML-Fragment
Live-Dokument als sanitisiertes HTML-Fragment für direkte Einbettung.
GET/v1/delivery/sites/{siteID}/documents/{typeCode}/pdf
PDF-Artefakt
Live-Dokument als PDF-Artefakt mit Content-Disposition zum Download oder Anhängen.

Nur GET wird unterstützt. Alle drei Endpunkte teilen sich dieselben Path-, Query-Parameter und Caching-Header.

Parameter & Delivery-Kontext

Pfad-Parameter

siteID: Pflicht. Site-Identifier aus dem Backoffice. Kein Workspace- oder Tenant-Bezug wird öffentlich exponiert.
typeCode: Pflicht. Stabiler Dokumenttyp-Code, z. B. privacy, terms, imprint.

Conditional-Request-Header

If-None-Match: Conditional GET. Stimmt der mitgesendete Wert mit dem aktuellen ETag überein, antwortet die API mit 304 Not Modified ohne Body.

Query-Parameter

locale: Locale-Code wie de-DE — wählt die Sprachfassung der veröffentlichten Version.
market: Markt-Code wie DE — wählt die marktspezifische Projektion.
profile: Site-Profil-Code wie B2C — wählt die profilspezifische Projektion.
version: Pinnt eine konkrete live geschaltete Version (positive Ganzzahl). Bei Abweichung antwortet die API mit 409 und nennt die aktuell live Version.
effective_at: Löst die Version auf, die zu diesem Zeitpunkt live ausgeliefert wurde — für „welche Fassung galt damals?“.
api: Optionaler Vertrags-Pin. Aktuell wird nur v1 akzeptiert.

Response-Header & Caching

Antworten sind cache-freundlich und tragen Versions- und Validierungs-Header:

ETag: Starker Validator aus Versionsnummer und Projektion — für Conditional GETs via If-None-Match.
Cache-Control: Cache-Direktive; kurze TTL für JSON/HTML, längere TTL für PDF, jeweils mit stale-while-revalidate.
Last-Modified: Zeitstempel der zuletzt gebauten Projektion (RFC 7231).
X-Termshelf-Document-Version: Numerische Version der ausgelieferten Zeile — bei 409 die aktuell live Version.
X-Termshelf-Published-At: ISO-8601-Zeitpunkt der Erstveröffentlichung des Dokuments.
Content-Disposition: Nur PDF. Erzwingt den Download mit deterministischem Dateinamen.
Content-Length: Nur PDF. Byte-Größe des Artefakts.
X-Correlation-Id: Pro-Request-Korrelations-ID — hilfreich beim Melden von Problemen.

Status- & Fehler-Codes

Fehler kommen als stabile JSON-Hülle { error: { code, message } }. Die wichtigsten Codes:

Status	Code
200	—	Erfolg. Artefakt im angeforderten Format mit Caching-Headern.
304	—	Conditional-GET-Treffer. Kein Body, nur ETag und Caching-Header.
400	invalid_request / unsupported_version	Ungültige Anfrage — z. B. fehlerhafter Parameter oder nicht unterstützter api-Pin.
403	entitlement_required	Der aufgelöste Plan berechtigt die angeforderte Artefaktform nicht.
404	not_found	Keine live geschaltete Projektion für die angefragte Kombination aus Site, Typ und Kontext.
405	method_not_allowed	Andere Methode als GET auf einem Delivery-Pfad.
409	version_mismatch	?version=N entspricht nicht der live Version; die Antwort nennt die aktuell live Version.
429	quota_exceeded / rate_limited	Rate-Limit pro IP oder Plan-Quota überschritten.
500	internal	Unerwarteter Serverfehler beim Lesen oder Rendern.
503	pdf_unavailable	Nur PDF-Endpoint. PDF-Auslieferung ist für diese Installation nicht konfiguriert.

Typische Integrationspfade

Website Legal Page: HTML-Fragment serverseitig in die Rechtstext-Seite einbetten; per ETag cachen.
SaaS-App Footer / Signup: Aktuelle Fassung im Footer oder Registrierungs-Flow anzeigen — JSON für eigenes Layout, HTML für direkte Einbettung.
Shop-Checkout / Bestellbestätigung: Beim Vertragsschluss die geltende Version pinnen und referenzieren.
Transaktionale E-Mail: HTML-Abschnitte direkt in die Mail einbetten oder JSON ins eigene Template rendern.
PDF-Anhang: Freigegebenes PDF-Artefakt abrufen und an Bestell-, Vertrags- oder Registrierungsmails anhängen.

Integrations-Checkliste

1Site und Profil bestimmen (siteID, ggf. profile/market).
2Dokumenttyp wählen (typeCode).
3Format wählen (JSON, HTML oder PDF).
4Versionierungsstrategie festlegen (live, version oder effective_at).
5Caching berücksichtigen (ETag, If-None-Match, Cache-Control).
6Fehlerbehandlung prüfen (403, 404, 409, 429 sauber behandeln).
7Juristische Inhalte extern prüfen bzw. freigeben lassen.

Weiterführend

Interaktive OpenAPI-3.1-Spezifikation

Vollständige Spec mit allen Schemas, Beispielen und „Try it“-Ansicht. Identisch zur statischen openapi.json oben.