Status-Lebenszyklus

Jeder Fall trägt genau einen Status. Über die externe API erreichst du Statuswechsel ausschließlich mit

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

Der Endpunkt fährt die interne Zustandsmaschine mit allen ihren Guards — er ist kein direktes Setzen des Feldes. Diese Seite beschreibt, welche Zielzustände du erreichen kannst, welche Bedingungen dafür gelten und was der Wechsel serverseitig auslöst.

Statuswerte

Enum-Wert	Bedeutung	Fall editierbar?	extern setzbar?
WORK_IN_PROGRESS	Entwurf: der Fall wird am Standort erfasst, noch nicht freigegeben	ja	ja
RELEASED	An den Fallabwickler freigegeben bzw. Gutachten liegt vor; releaseDate wird gestempelt	ja	ja
HANDED_OVER_APPRAISER	An das Gutachterbüro übergeben, wartet auf das Gutachten	ja	ja
CLOSED	Abgeschlossen; closedDate wird gestempelt	nein	ja
CANCELLED	Storniert; Begründung steht in additionalInfos	nein	ja (Begründung Pflicht)
WAITING_FOR_CUSTOMER	Kundenportal „Kunde hilft mit" läuft	ja	nein — 409
HIDDEN	Soft-Delete: der Fall verschwindet aus allen Abfragen	nein	nein — 400

HIDDEN lehnt der externe Endpunkt schon vor dem Fachaufruf mit 400 VALIDATION ab („Der Status HIDDEN (Soft-Delete) ist über die externe API nicht setzbar."). WAITING_FOR_CUSTOMER gehört dem Kundenportal: die Zustandsmaschine weist jeden Wechsel dorthin mit 409 CONFLICT ab, und aus WAITING_FOR_CUSTOMER heraus sind RELEASED und HANDED_OVER_APPRAISER ebenfalls gesperrt (erst muss das Portal beendet werden — das übernimmt die Plattform, nicht deine Integration). Der Fall bleibt dabei aber editierbar: WAITING_FOR_CUSTOMER ist ein aktiver Status, Schreiben von Falldaten, Anhängen und Kommentaren funktioniert normal — nur der Statuswechsel ist gesperrt.

Übergänge

Nicht im Diagramm, weil extern nicht auslösbar: der automatische Rückfall HANDED_OVER_APPRAISER → WORK_IN_PROGRESS nach fehlgeschlagener Übergabe an das Gutachter-System, die automatische Freigabe durch den Gutachten-Sync, der Admin-Force-Release und der Soft-Delete nach HIDDEN.

Request und Antwort

curl -sS -X PUT https://usp.linkki.de/api/external/v1/cases/$CASE_ID/status \
  -H "Authorization: Bearer $USP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"RELEASED"}'

{
  "caseId": "5f4d1c2e-9b1a-4f3e-8c2d-1a2b3c4d5e6f",
  "status": "RELEASED",
  "changed": true,
  "lastModifiedDate": "2026-07-20T09:41:07.812"
}

Feld	Bedeutung
status (Request)	Zielstatus, Pflicht. Fehlt er, kommt 400 VALIDATION
reason (Request)	Nur bei status=CANCELLED ausgewertet und dort Pflicht; sonst ignoriert
changed (Antwort)	false, wenn der Fall den Zielstatus bereits hatte (No-Op ohne Events)
lastModifiedDate (Antwort)	frischer Sperr-Zeitstempel — übernimm ihn als Baseline für das nächste PUT /cases/{caseId}

Kein Optimistic-Lock-Parameter. Anders als beim Fall-Update musst du hier keinen Zeitstempel mitschicken: der Endpunkt lädt den Fall frisch und erfüllt die Sperre serverseitig. Das ist bewusst so, weil ein Statuswechsel kein Feld-Merge ist.

Die Übergänge im Detail

Freigabe → RELEASED

• Vorbedingung: ein Anhang mit Tag POA_SIGNED oder OWN_PROCESSING_POA_SIGNED („Vollmacht bzw. RKÜ unterschrieben") muss am Fall existieren. Ausnahme: Fälle in Eigenbearbeitung (processingType = OWN_PROCESSING) brauchen keine Vollmacht. Fehlt sie ⇒ 409 CONFLICT.
• Effekte: releaseDate wird gestempelt; der Fallabwickler-Standort bekommt die Mail CASE_RELEASED (abhängig von seiner Mail-Präferenz) und eine Benachrichtigung; Fallhistorie und CaseUpdatedEvent laufen mit.
• Die Vorbedingung greift nur mit Ausgangsstatus WORK_IN_PROGRESS — ein Wiedereröffnen aus CLOSED/CANCELLED prüft sie nicht.

Übergabe → HANDED_OVER_APPRAISER

• Vorbedingung: signierter Gutachtenauftrag (EXPERT_OPINION_ORDER_SIGNED) und — außer bei Eigenbearbeitung — signierte Vollmacht. Sonst 409 CONFLICT.
• Effekte: nach dem Commit übergibt die Plattform den Fall an das Gutachtersystem. Scheitert das, setzt sie den Fall automatisch auf WORK_IN_PROGRESS zurück — dein nächstes Delta zeigt den Fall dann wieder als Entwurf. Es gibt für die Übergabe keine Mail.
• Sinnvoll nur, wenn das Gutachterbüro des Falls eine API-Anbindung hat. Ohne sie gehört der Fall auf RELEASED.

Abschließen → CLOSED

• Vorbedingung: die Person hinter dem Grant muss dem Fallabwickler-Standort angehören oder Admin-Rechte haben; bei Fällen in Eigenbearbeitung darf jede_r Standort-Nutzer_in abschließen. Sonst 403 ACCESS_DENIED.
• Effekte: closedDate wird gestempelt, eine CASE_CLOSED-Benachrichtigung entsteht. Eine Abschluss-Mail gibt es bewusst nicht.
• Danach ist der Fall read-only: PUT /cases/{caseId} antwortet 409, Uploads ebenfalls.

Stornieren → CANCELLED

• Vorbedingung: reason im Request ist Pflicht. Der Endpunkt schreibt ihn zuerst als additionalInfos an den Fall (nur wenn er dort nicht schon exakt so steht) und führt danach den Statuswechsel aus — der interne Storno-Guard prüft nämlich den persistierten Wert.
• Folge daraus: Ist der Fall gerade nicht editierbar, scheitert schon das Schreiben der Begründung mit 409 CONFLICT. Ein bereits abgeschlossener Fall lässt sich also nicht in einem Schritt stornieren — erst wiedereröffnen.
• Effekte: ein vorhandenes releaseDate wird geleert. Es gibt keine Storno-Mail und keine Storno-Benachrichtigung, nur Fallhistorie und CaseUpdatedEvent.

Wiedereröffnen → RELEASED (aus CLOSED/CANCELLED)

• Vorbedingung: aus CLOSED verlangt der Server Fallabwickler-Zugehörigkeit bzw. Admin-Rechte; aus CANCELLED prüft er keine Zusatzberechtigung.
• Effekte: releaseDate wird neu gestempelt, closedDate geleert. Keine erneute Freigabe-Mail — das Freigabe-Event feuert nur aus dem Entwurf heraus.

Read-only-Semantik

Editierbar ist ein Fall in WORK_IN_PROGRESS, RELEASED, HANDED_OVER_APPRAISER und WAITING_FOR_CUSTOMER (CaseService.isEditable). Auf CLOSED, CANCELLED und HIDDEN antworten die schreibenden Endpunkte mit 409 CONFLICT.

Externer Endpunkt	Status-Gate?
PUT /cases/{caseId}	ja — nur editierbare Fälle
POST /cases/{caseId}/attachments	ja — nur editierbare Fälle
PUT /cases/{caseId}/status	nein — Statuswechsel sind gerade für Endzustände gedacht
PUT /cases/{caseId}/tags	nein
PUT /cases/{caseId}/evaluation-values	nein
DELETE /attachments/{attachmentId}	nein
POST /cases/{caseId}/comments	nein — Kommentare sind in jedem Status erlaubt
alle GET	nein

Verlass dich also nicht darauf, dass ein abgeschlossener Fall vollständig unveränderlich ist.

Fehlerbilder dieses Endpunkts

HTTP	code	Wann
400	VALIDATION	caseId keine gültige UUID, status fehlt, status=HIDDEN, oder Storno ohne reason
403	ACCESS_DENIED	Key ohne Scope cases:status; oder der Übergang verlangt Fallabwickler-/Admin-Rechte, die die Grant-Person nicht hat
404	NOT_FOUND	Fall unbekannt, fremder Mandant oder außerhalb der Sichtbarkeit
409	CONFLICT	Wechsel nach/aus WAITING_FOR_CUSTOMER; fehlende signierte Dokumente für Freigabe/Übergabe; Fall nicht editierbar beim Schreiben der Storno-Begründung

Ablauf und Beispiele: Fall freigeben und abschließen. Alle Codes: Fehlercodes.