Einstieg

Zweck & Zielgruppe

Diese Doku richtet sich an Entwickler_innen bei Werkstätten, Fallabwicklern (Case Handlern) und Gutachterbüros, die ein Fremdsystem an die Unfallschadenplattform anbinden — also Fälle maschinell anlegen, lesen, aktualisieren, Dokumente austauschen und Kommentare schreiben. Der Zugang läuft ausschließlich über einen Benutzer-API-Key und die versionierte API unter /api/external/v1. Was dein Key sieht und darf, bestimmt der Typ deines Mandanten — die Werkstatt-, Fallabwickler- oder Gutachter-Sicht (siehe „Mandantenbindung" unten).

Sicht-Markierung: Gilt eine Fähigkeit nicht für alle drei Sichten gleich, steht am Abschnitt eine Zeile wie Sicht: Werkstatt · Fallabwickler. Ohne Markierung gilt der Abschnitt für alle.

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?

Was die externe API ist

• Basis-URL: <host>/api/external/v1 — z. B. https://usp.linkki.de/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 drei 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; ein Gutachter-Key (Büro) sieht die Fälle, denen sein Büro als Gutachter (expertOfficeCode) zugewiesen ist — auch Fälle in Eigenbearbeitung. Über die Fallabwickler-Sicht sind Eigenbearbeitungs-Fälle (OWN_PROCESSING) dagegen 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".

Versionierung

• 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 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)	Methode	Scope	Seite
/me	GET	(nur gültiger Key)	Authentifizierung und Scopes
/cases	GET	cases:read	Übersicht und Bearbeitung
/cases	POST	cases:write	Fallanlage
/cases/{caseId}	GET	cases:read	Übersicht und Bearbeitung
/cases/{caseId}	PUT	cases:write	Übersicht und Bearbeitung
/cases/{caseId}/status	PUT	cases:status	Fall freigeben und abschließen
/cases/{caseId}/tags	GET	cases:read	Fall freigeben und abschließen
/cases/{caseId}/tags	PUT	cases:write	Fall freigeben und abschließen
/cases/{caseId}/evaluation-values	GET	cases:read	Übersicht und Bearbeitung
/cases/{caseId}/evaluation-values	PUT	cases:write	Übersicht und Bearbeitung
/cases/{caseId}/attachments	GET	attachments:read	Anhänge verwalten
/cases/{caseId}/attachments	POST	attachments:write	Anhänge verwalten
/attachments/{attachmentId}	GET	attachments:read	Anhänge verwalten
/attachments/{attachmentId}/tag	PUT	attachments:write	Anhänge verwalten
/attachments/{attachmentId}/content	GET	attachments:read	Anhänge verwalten
/attachments/{attachmentId}	DELETE	attachments:write	Anhänge verwalten
/cases/{caseId}/comments	GET	comments:read	Kommentare
/cases/{caseId}/comments	POST	comments:write	Kommentare
/comments/{commentId}	PUT	comments:write	Kommentare
/locations	GET	reference-data:read	Stammdaten
/locations/{locationCode}	GET	reference-data:read	Stammdaten
/case-handlers	GET	reference-data:read	Stammdaten
/users	GET	reference-data:read	Stammdaten
/users/{username}	GET	reference-data:read	Stammdaten
/insurances, /insurances/{id}	GET	reference-data:read	Stammdaten
/insurances	POST	reference-data:write	Stammdaten
/insurances/{id}	PUT	reference-data:write	Stammdaten
/legal-insurances, /legal-insurances/{id}	GET	reference-data:read	Stammdaten

Noch nicht verfügbar: 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

• Fallanlage — wie neue Fälle entstehen, wie du per POST /cases selbst welche anlegst und wie du sie findest.
• Übersicht und Bearbeitung — Fälle listen, Delta abholen, einzeln lesen und mit Optimistic Lock zurückschreiben.
• Anhänge verwalten — Dateien listen, hochladen, herunterladen und löschen.
• Kommentare — Kommentarverlauf lesen und Kommentare anhängen.
• Fall freigeben und abschließen — Statuswechsel und Fall-Tags (z. B. Haftungsbestätigung).

Referenz

• Fehlercodes — alle code-Werte, die die API 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.
• 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.