Fall freigeben und abschließen

Ziel

Du steuerst den Lebenszyklus eines Falls von außen: freigeben, an den Gutachter übergeben, abschließen, wiedereröffnen, stornieren — und den Fortschritt über Fall-Tags markieren, allen voran die Haftungsbestätigung.

Der komplette Statusgraph mit allen Guards steht unter Status-Lebenszyklus; hier geht es um den Ablauf.

Voraussetzungen

• Scopes: cases:status für Statuswechsel, cases:write für Fall-Tags, cases:read zum Lesen von Status und Tags. attachments:read hilft, die Freigabe-Voraussetzungen vorab zu prüfen.
• Sichtbarkeit: Fall im Mandanten des Keys und für die Grant-Person sichtbar, sonst 404.
• Rechte der Grant-Person: Abschließen und Wiedereröffnen (aus CLOSED) verlangen Fallabwickler-Zugehörigkeit oder Admin-Rechte — außer bei Eigenbearbeitung. Ein Key kann nie mehr als die Person dahinter.
• Dokumente: Freigabe braucht eine signierte Vollmacht/RKÜ, die Gutachter-Übergabe zusätzlich einen signierten Gutachtenauftrag (jeweils außer bei Eigenbearbeitung).

Übergänge im Überblick

Aktion	Übergang	Request-Body	Server-Guard
Freigeben	WORK_IN_PROGRESS → RELEASED	{"status":"RELEASED"}	signierte Vollmacht/RKÜ (außer Eigenbearbeitung)
An Gutachter übergeben	WORK_IN_PROGRESS → HANDED_OVER_APPRAISER	{"status":"HANDED_OVER_APPRAISER"}	signierter Gutachtenauftrag + Vollmacht
Abschließen	WORK_IN_PROGRESS/RELEASED/HANDED_OVER_APPRAISER → CLOSED	{"status":"CLOSED"}	Fallabwickler-/Admin-Recht (außer Eigenbearbeitung)
Wiedereröffnen	CLOSED/CANCELLED → RELEASED	{"status":"RELEASED"}	aus CLOSED: Fallabwickler-/Admin-Recht
Stornieren	editierbarer Fall → CANCELLED	{"status":"CANCELLED","reason":"…"}	reason ist Pflicht
Fortschritt markieren	kein Statuswechsel	{"tag":"LIABILITY_CONFIRMATION_ISSUED"}	—

Nicht extern verfügbar: Soft-Delete (HIDDEN, 400), Kundenportal-Status (WAITING_FOR_CUSTOMER, 409) und der Admin-Force-Release.

1. Voraussetzungen prüfen (optional, aber empfohlen)

Der Server prüft alles selbst — du sparst dir aber einen 409, wenn du vorher schaust:

GET /api/external/v1/cases/{caseId}                  → status, processingType
GET /api/external/v1/cases/{caseId}/attachments      → tags der Anhänge

Freigabe möglich, wenn processingType == "OWN_PROCESSING" oder ein Anhang den Tag POA_SIGNED bzw. OWN_PROCESSING_POA_SIGNED trägt. Übergabe zusätzlich: ein Anhang mit EXPERT_OPINION_ORDER_SIGNED.

Diese Dokumente kannst du extern nicht erzeugen oder signieren — das passiert in der Oberfläche bzw. über den externen Signaturprozess mit der Kund_in. Deine Integration wartet also darauf, dass der Tag auftaucht.

2. Statuswechsel auslösen

PUT /api/external/v1/cases/{caseId}/status        (Scope cases:status)

curl -sS -X PUT https://dev.devlodge.site/api/external/v1/cases/$CASE_ID/status \
  -H "Authorization: Bearer $USP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"CLOSED"}'

{ "caseId": "5f4d…", "status": "CLOSED", "changed": true, "lastModifiedDate": "2026-07-20T09:41:07.812" }

• Kein Optimistic-Lock-Parameter — der Endpunkt erfüllt die Sperre serverseitig aus dem frisch geladenen Fall.
• changed: false heißt: der Fall hatte den Status schon, es ist nichts passiert (kein Event, keine Mail). Das ist kein Fehler — dein Retry nach einem Timeout landet genau hier.
• Übernimm lastModifiedDate aus der Antwort als neue Baseline für spätere PUT /cases/{caseId}.

Storno mit Begründung

{ "status": "CANCELLED", "reason": "Kunde hat den Auftrag zurueckgezogen." }

Die Begründung ist Pflicht (sonst 400 VALIDATION). Der Endpunkt schreibt sie zuerst in das Feld additionalInfos des Falls — der interne Storno-Guard prüft nämlich den persistierten Wert — und führt danach den Statuswechsel aus. Steht dort bereits exakt derselbe Text, spart er sich den Schreibvorgang.

Daraus folgt: ein nicht editierbarer Fall lässt sich nicht stornieren. Schon das Schreiben der Begründung scheitert dann mit 409. Einen abgeschlossenen Fall musst du erst wiedereröffnen.

Ein reason bei jedem anderen Zielstatus wird ignoriert.

3. Was ein Statuswechsel auslöst

Zielstatus	Zeitstempel	Mail	Benachrichtigung
RELEASED (aus WORK_IN_PROGRESS)	releaseDate gesetzt	CASE_RELEASED an den Fallabwickler-Standort (je nach Mail-Präferenz; unterdrückt bei Eigenbearbeitung)	ja
RELEASED (Wiedereröffnen)	releaseDate neu, closedDate geleert	keine Freigabe-Mail	—
HANDED_OVER_APPRAISER	—	keine	keine; nach dem Commit läuft die Übergabe ans Gutachtersystem
CLOSED	closedDate gesetzt	keine (es gibt bewusst keine Abschluss-Mail)	CASE_CLOSED
CANCELLED	releaseDate geleert	keine	keine

Jeder erfolgreiche Wechsel schreibt zusätzlich einen Fallhistorie-Eintrag.

Ein Sonderfall, den du im Delta sehen wirst: Scheitert die Übergabe an das Gutachtersystem, setzt die Plattform den Fall automatisch auf WORK_IN_PROGRESS zurück. Prüfe nach einem Handover also später den tatsächlichen Status, statt ihn anzunehmen.

4. Fall-Tags: Fortschritt markieren

Fall-Tags sind kein Statuswechsel, sondern Fortschrittsmarken am Fall. Der klassische Rückkanal eines Fallabwickler-Systems ist die Haftungsbestätigung.

GET /api/external/v1/cases/{caseId}/tags        (Scope cases:read)
PUT /api/external/v1/cases/{caseId}/tags        (Scope cases:write)

curl -sS -X PUT https://dev.devlodge.site/api/external/v1/cases/$CASE_ID/tags \
  -H "Authorization: Bearer $USP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag":"LIABILITY_CONFIRMATION_ISSUED"}'

Beide Aufrufe antworten mit der kompletten Tag-Liste des Falls:

[ { "tag": "LIABILITY_CONFIRMATION_ISSUED", "hidden": false, "createdDate": "2026-07-20T09:44:11" } ]

Wert	Bedeutung
LIABILITY_CONFIRMATION_ISSUED	Die gegnerische Versicherung hat die Haftung bestätigt
RENTAL_CAR_PRICE_INFORMATION_RECEIVED	Mietwagen-Preisinformation liegt vor
ADVANCE_RECEIVED	Vorschuss ist eingegangen
NONE	Platzhalter — wird mit 400 VALIDATION abgelehnt

Eigenschaften:

• Idempotent: ein bereits vorhandener Tag ist ein No-Op, kein Fehler. Doppelte Aufrufe sind für eine Integration normal und ausdrücklich erlaubt.
• Kein Status-Gate: Tags lassen sich auch an nicht editierbaren Fällen setzen.
• Seiteneffekte: Der Aufruf stempelt lastSynced am Fall, schreibt einen Historieneintrag — und schiebt damit lastModifiedDate vor. LIABILITY_CONFIRMATION_ISSUED löst zusätzlich die Mail LIABILITY_CONFIRMATION an das Postfach des Fall-Standorts aus (nicht des Fallabwicklers), abhängig von Fallstatus, Bearbeitungsart und Mail-Präferenz des Standorts.
• Kein Entfernen: einen gesetzten Tag wieder wegzunehmen ist extern nicht möglich.
• Die Antwort enthält auch versteckte Tags (hidden: true); die interne Zeilen-ID wird nicht ausgeliefert.

Was kann schiefgehen?

HTTP	code	Wann	Was tun
400	VALIDATION	status fehlt, status=HIDDEN, Storno ohne reason, tag fehlt oder ist NONE, ungültige UUID	Request korrigieren
403	ACCESS_DENIED	Key ohne cases:status/cases:write; oder der Übergang verlangt Fallabwickler-/Admin-Rechte, die die Grant-Person nicht hat	Scopes prüfen; Aktion einer berechtigten Person überlassen
404	NOT_FOUND	Fall unbekannt, fremder Mandant oder außerhalb der Sichtbarkeit	caseId prüfen
409	CONFLICT	Freigabe ohne signierte Vollmacht; Übergabe ohne Gutachtenauftrag/Vollmacht; Wechsel nach/aus WAITING_FOR_CUSTOMER; Fall beim Schreiben der Storno-Begründung nicht editierbar	fehlendes Dokument abwarten; bei Storno erst wiedereröffnen
429	RATE_LIMITED / API_RATE_LIMITED	Rate-Limit erreicht	Retry-After abwarten

Sequenzdiagramm