Zum Hauptinhalt springen

Public API – Konventionen

Datenformate, Datum und Zeitzone, Listen, sichere Wiederholungen und Versionierung der Public API.

Verfasst von Support Team

Diese Regeln gelten für alle Endpunkte. Wenn du sie einmal kennst, liest sich jede Endpunkt-Beschreibung schneller.

Anfragen

  • JSON-Body. POST- und PATCH-Anfragen schicken einen JSON-Body in UTF-8. Setze Content-Type: application/json.

  • Ausnahme Dokument-Upload. POST /cases/{uuid}/documents erwartet multipart/form-data.

  • Ungültiges JSON führt in der Regel zu 400 mit Ungültige Anfrage.

  • Unbekannte Felder werden ignoriert – ohne Fehlermeldung. Ein Tippfehler im Feldnamen ändert also nichts. Prüfe deshalb in der Antwort, ob dein Wert angekommen ist.

  • Teiländerungen mit PATCH. Du schickst nur die Felder, die sich ändern sollen. PUT wird nicht unterstützt.

  • Pfad-Parameter wie {uuid} sind UUIDs im Format 8-4-4-4-12 (zum Beispiel 3f8c2a91-6d4e-4b7a-9c15-8e2f0b6d1a47). Eine falsch aufgebaute UUID führt zu 400, eine unbekannte zu 404.

Antworten

Jede JSON-Antwort hat dieselbe Hülle:

{ "success": true, "data": { } }

Feld

Wann

Beschreibung

success

immer

true bei Erfolg, false bei einem Fehler

data

bei Erfolg

Ein Objekt oder eine Liste

count

bei Listen von Trauerfällen, Terminen und Dokumenten

Anzahl der Einträge in data

message

bei manchen Aktionen

Kurzer Text, zum Beispiel Dokument hochgeladen

error

bei Fehlern

Kurzbeschreibung des Fehlers

Die Listen der Referenzdaten (/burial-types, /branches, /users, /document-tags) haben kein count.

Einzige Ausnahme vom JSON-Format: GET /documents/{uuid}/download liefert die Datei selbst.

Neue Felder können jederzeit dazukommen. Baue deine Integration so, dass sie unbekannte Felder ignoriert.

Datentypen

Art

Format

Beispiel

Interne IDs (Bestattungsart, Standort, Mitarbeiter, Tag)

Integer

6

Trauerfälle, Termine, Dokumente

UUID als String

"3f8c2a91-6d4e-4b7a-9c15-8e2f0b6d1a47"

Schalter (feature_*, has_time, is_public, is_paused …)

Integer 0 oder 1

1

Einzelne Ja/Nein-Felder (has_preview, location_stored)

Boolean

true

Datum

String YYYY-MM-DD

"2026-11-10"

Zeitpunkt (die meisten Felder)

String YYYY-MM-DD HH:MM:SS

"2026-11-10 14:32:05"

Zeitpunkt mit Zeitzone (tag_last_seen_at, link_last_visit_at)

ISO 8601

"2026-11-11T08:14:57+01:00"

Koordinaten an Trauerfällen und Adressen

String mit Dezimalpunkt

"52.51627600"

Koordinaten an Terminen

Zahl

52.50412

Leere Werte

null

null

Beim Senden darfst du Schalter als 0/1 oder true/false schicken und Koordinaten als Zahl. In Antworten kommen Koordinaten von Trauerfällen und Adressen als String – wandle sie bei Bedarf in eine Zahl um.

Datum und Zeitzone

  • Zeitpunkte ohne Zeitzonen-Angabe sind Ortszeit der Region (Deutschland: Europe/Berlin, Niederlande: Europe/Amsterdam, also MEZ bzw. MESZ).

  • Schicke Termin-Zeitpunkte ebenfalls in Ortszeit und ohne Zeitzone, zum Beispiel 2026-11-20 11:00:00.

  • Felder im ISO-8601-Format tragen die Abweichung zu UTC mit (+01:00).

  • Webhooks senden triggered_at in UTC (+00:00) – siehe Webhooks.

Listen und Paginierung

Es gibt keine Paginierung. Jede Liste liefert alle Einträge auf einmal.

  • GET /cases liefert alle nicht archivierten Trauerfälle, neueste zuerst. Archivierte holst du mit ?status=archived.

  • Termine sind nach Zeitpunkt sortiert, Dokumente nach Upload (neueste zuerst).

  • Weitere Filter oder eine Suche gibt es nicht.

Rufe große Listen deshalb nicht in kurzen Abständen ab. Referenzdaten wie Bestattungsarten und Mitarbeiter ändern sich selten – speichere sie zwischen.

Wiederholen und Idempotenz

Die API kennt keine Idempotenz-Schlüssel. Ob du einen Request gefahrlos wiederholen kannst, hängt vom Endpunkt ab:

Wiederholung

Endpunkte

Unkritisch

Alle GET-Anfragen, PATCH mit denselben Werten (ohne current_step_index), POST /cases/{uuid}/archive, POST /cases/{uuid}/dates mit step_id (ersetzt den Termin des Schritts), DELETE (beim zweiten Mal 404)

Liefert beim zweiten Mal 409

POST /cases/{uuid}/complete, POST /cases/{uuid}/tag

Erzeugt ein Duplikat

POST /cases, POST /cases/{uuid}/dates ohne step_id, POST /cases/{uuid}/documents

Löst Folgeaktionen erneut aus

POST /cases/{uuid}/step und PATCH mit current_step_index – Webhooks für den Schritt werden erneut gesendet

Bekommst du bei einem anlegenden Request einen Timeout, prüfe vor dem Wiederholen per GET, ob der Datensatz schon existiert. Speichere die uuid aus der Antwort in deinem System, damit du Trauerfälle später eindeutig zuordnen kannst.

Versionierung

  • Die Version steht im Pfad: /api/public/v1. Aktuell gibt es nur v1.

  • Jede Antwort unter /v1 hat den Header X-API-Version: v1.

  • Neue Felder und neue Endpunkte kommen ohne neue Version. Inkompatible Änderungen gibt es nur mit einer neuen Version.

  • Ein Pfad ohne Version oder mit unbekannter Version antwortet mit 404:

{
  "success": false,
  "error": "API-Version fehlt. Nutze /api/public/v1",
  "supported_versions": ["v1"]
}

Lege die Basis-URL inklusive /v1 an einer Stelle in deiner Integration ab. Dann ist ein späterer Wechsel eine Änderung an einer Stelle.

Sprache der Meldungen

Fehler- und Erfolgsmeldungen kommen in der Sprache der Region: auf de Deutsch, auf nl Englisch. Einzelne Meldungen sind immer englisch (zum Beispiel Authorization required). Werte in deiner Integration den HTTP-Statuscode aus, nie den Text.

Aufrufe aus dem Browser

Die API erlaubt Aufrufe von jeder Herkunft (CORS). Trotzdem gilt: API-Keys gehören nicht in Browser-Code. Wenn du doch aus dem Browser aufrufst, kann dein Code die Header Retry-After und X-API-Version nicht lesen – nutze bei 429 das Feld retry_after im Body.

Hat dies deine Frage beantwortet?