Zum Hauptinhalt springen

Einstieg

Zweck & Zielgruppe​

Diese Doku richtet sich an Entwickler_innen bei Fallabwicklern (Case Handlern), die ein Fremdsystem an die Unfallschadenplattform anbinden — also Fälle maschinell lesen, aktualisieren, Dokumente austauschen und Kommentare schreiben. Der Zugang läuft ausschließlich über einen Benutzer-API-Key und die versionierte externe Fläche unter /api/external/v1.

Sie beantwortet die Fragen, die ein OpenAPI-Schema nicht beantwortet: In welcher Reihenfolge rufe ich welche Endpunkte auf, um einen fachlichen Vorgang abzuschließen? Welchen Scope braucht mein Key dafür? Welche Vorbedingungen prüft der Server, und was passiert intern (Mails, Historie), wenn ich schreibe?

Jede Aussage hier ist aus dem Quellcode der externen Controller belegt. Wo etwas (noch) nicht existiert, steht das als Noch nicht verfügbar im Text — statt es zu erfinden.

Was die externe API ist​

  • Basis-URL: <host>/api/external/v1 — z. B. https://dev.devlodge.site/api/external/v1.
  • Authentifizierung: genau ein Header Authorization: Bearer usp_<env>_<publicId>_<secret>. Das ist der einzige Weg — keine Cookies, kein Token im Query-String, kein zweiter Header. Details: Authentifizierung und Scopes.
  • Mandantenbindung: ein Key gehört zu genau einem Mandanten (Standort-Teilbaum). Für Fälle gibt es zwei Sichten: ein Werkstatt-Key (z. B. musterhaus) sieht die Fälle, deren Standort im Teilbaum liegt; ein Fallabwickler-Key (z. B. musterhandler) sieht die Fälle, deren caseHandler im Teilbaum liegt — also die ihm zugewiesenen Fälle, egal in welcher Werkstatt sie liegen. Fälle in Eigenbearbeitung (OWN_PROCESSING) sind über die Fallabwickler-Sicht nie sichtbar. Ressourcen außerhalb des Mandanten existieren für den Key nicht — die Antwort ist 404, nie 403.
  • Autorisierung: jeder Endpunkt trägt genau einen Scope (cases:read, cases:write, cases:status, attachments:read, attachments:write, comments:read, comments:write, reference-data:read, reference-data:write). Kein Wildcard, kein „full access".
  • Feature-Flags: die Fläche ist standardmäßig dunkel geschaltet und hängt an zwei unabhängigen Schaltern. platform.api-keys.authentication-enabled registriert die API-Key-Security-Chain für /api/external/v1/**; platform.api-keys.external-api-enabled registriert die Controller. Daraus folgen drei Bilder: beide true ⇒ die API antwortet; nur die Authentifizierung true ⇒ der Key wird geprüft, es existiert aber keine Route ⇒ 404; die Authentifizierung false ⇒ die Pfade antworten für einen API-Key 401.

Versionierung und Abgrenzung​

  • v1 ist der Vertrag. Der Pfad trägt die Version. Innerhalb von v1 werden Felder additiv ergänzt; Clients müssen unbekannte JSON-Felder tolerieren. Ein Bruch bekommt einen neuen Pfad-Präfix (/api/external/v2), nicht ein neues Feldverhalten unter v1.
  • Die interne SPA-API ist NICHT Teil dieses Vertrags. Alles unter /api/v1/**, /api/admin/**, /api/user/**, /api/overview/**, /api/integration/** und /api/history/** gehört zur Vue-3- Oberfläche bzw. zur Administration und kann sich jederzeit ändern. Ein API-Key kommt dort per Design nicht hinein: die Key-Chain matcht ausschließlich /api/external/v1/**.
  • Keine Admin-Fähigkeiten extern. Benutzer und Standorte anlegen, Policies, Analytics, E-Mail-Log, Integrations-Monitoring, Signaturprozesse und Kundenportal-Verwaltung sind bewusst nicht Teil der externen Fläche und werden es auch nicht.

Die Plattform in Kürze​

Die Plattform ist eine deutsche Unfallschadenplattform: Werkstätten und Fuhrparks (Standorte) erfassen Unfallschäden ihrer Kund_innen als „Fälle" und geben sie an einen Fallabwickler zur Regulierung ab. Ein Fall entsteht als Entwurf (WORK_IN_PROGRESS), wird mit Falldaten und Anhängen befüllt, freigegeben (RELEASED) oder an ein Gutachterbüro übergeben (HANDED_OVER_APPRAISER) und am Ende abgeschlossen (CLOSED) oder mit Begründung storniert (CANCELLED). Der komplette Graph steht unter Status-Lebenszyklus, die Fachbegriffe im Glossar.

Für dich als Integrator ist die wichtigste Eigenschaft: Sichtbarkeit ist serverseitig doppelt begrenzt — auf die Standorte der Person, zu der dein Key gehört, und zusätzlich auf den Mandanten des Keys.

Endpunkte auf einen Blick​

Pfad (relativ zu /api/external/v1)MethodeScopeSeite
/meGET(nur gültiger Key)Authentifizierung und Scopes
/casesGETcases:readÜbersicht und Bearbeitung
/cases/{caseId}GETcases:readÜbersicht und Bearbeitung
/cases/{caseId}PUTcases:writeÜbersicht und Bearbeitung
/cases/{caseId}/statusPUTcases:statusFall freigeben und abschließen
/cases/{caseId}/tagsGETcases:readFall freigeben und abschließen
/cases/{caseId}/tagsPUTcases:writeFall freigeben und abschließen
/cases/{caseId}/evaluation-valuesGETcases:readÜbersicht und Bearbeitung
/cases/{caseId}/evaluation-valuesPUTcases:writeÜbersicht und Bearbeitung
/cases/{caseId}/attachmentsGETattachments:readAnhänge verwalten
/cases/{caseId}/attachmentsPOSTattachments:writeAnhänge verwalten
/attachments/{attachmentId}GETattachments:readAnhänge verwalten
/attachments/{attachmentId}/contentGETattachments:readAnhänge verwalten
/attachments/{attachmentId}DELETEattachments:writeAnhänge verwalten
/cases/{caseId}/commentsGETcomments:readKommentare
/cases/{caseId}/commentsPOSTcomments:writeKommentare
/locationsGETreference-data:readStammdaten
/locations/{locationCode}GETreference-data:readStammdaten
/case-handlersGETreference-data:readStammdaten
/usersGETreference-data:readStammdaten
/users/{username}GETreference-data:readStammdaten
/insurances, /insurances/{id}GETreference-data:readStammdaten
/insurancesPOSTreference-data:writeStammdaten
/insurances/{id}PUTreference-data:writeStammdaten
/legal-insurances, /legal-insurances/{id}GETreference-data:readStammdaten

Noch nicht verfügbar: Fälle anlegen, Anhang-Tags setzen, Kommentare bearbeiten, Dokumente erzeugen/signieren, Fallhistorie lesen, Kundenportal steuern. Siehe die jeweilige Workflow-Seite.

Aufbau der Doku​

Grundlagen​

  • Authentifizierung und Scopes — Key-Format, Header, Mandantenbindung, kompletter Scope-Katalog, Rate-Limits und die 401/403/404-Semantik.
  • Status-Lebenszyklus — die Statuswerte und alle Übergänge, die du über PUT /cases/{caseId}/status auslösen kannst.
  • Glossar — die extern sichtbaren Fachbegriffe mit ihren Code-Bezeichnern.

Workflows​

Referenz​

  • Fehlercodes — alle code-Werte, die die externe Fläche zurückgibt.
  • Stammdaten — Standorte, Fallabwickler, Kolleg_innen, Versicherungen.
  • Schlüsselverwaltung — wie eine Integration an einen Key kommt, Rotation, Widerruf, Kompromittierung.
  • Integrator-Kochbuch — die typische Sync-Schleife als konkrete Aufruffolge mit curl-Beispielen.

API-Konventionen kompakt​

  • Fehlerformat: fachliche Fehler antworten mit passendem HTTP-Status und JSON-Body { "code": "...", "message": "..." }; Serverfehler mit { "code": "INTERNAL_ERROR", "errorId": "<uuid>" } — die errorId ist die Referenz für den Support. Der code ist stabil; der Katalog steht unter Fehlercodes.
  • Pfad-Muster: ressourcenorientiert (/cases/{id}/attachments), keine Verb-Segmente. Die internen get/-/put/-Pfade der SPA-API gibt es hier bewusst nicht.
  • Optimistic Locking: PUT /cases/{caseId} trägt das zuletzt gelesene lastModifiedDate mit; bei Konflikt antwortet der Server mit HTTP 400 und code ALREADY_MODIFIED (nicht 409).
  • Zeitstempel: ISO-8601 lokale Datums-/Zeitwerte ohne Zone (2026-07-17T06:00:00), so wie die Plattform sie auch persistiert. Nur /me liefert mit serverTime einen Wert mit Offset.
  • Upload-Limit: Multipart-Uploads sind auf 20 MB pro Datei und Request begrenzt.
  • Idempotenz: Wiederholte PUTs sind unkritisch, solange der Optimistic Lock passt; PUT /cases/{caseId}/tags ist explizit idempotent. POST (Anhang, Kommentar, Versicherung) ist es nicht — ein Retry nach Timeout kann doppelte Datensätze erzeugen.