Zum Hauptinhalt springen

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 verlangt Fallabwickler-Zugehörigkeit (der Betreiber zählt dazu); einen Fall in Eigenbearbeitung dürfen zusätzlich die Personen seines Standorts (bzw. Hauptstandorts) abschließen — nicht das Gutachterbüro, dem er zugewiesen ist. Wiedereröffnen aus CLOSED gehört den Fallabwicklern und dem Betreiber, egal in welches Ziel; die Rolle USP_ADMIN allein genügt dafür nicht. Ein Key kann nie mehr als die Person dahinter. Wohin, bestimmt der Fall: in seinen Status vor dem Abschließen (reopenTarget) oder in den Entwurf WORK_IN_PROGRESS. Die Rücknahme eines Soft-Deletes (HIDDEN) bleibt dagegen dem Betreiber vorbehalten — und zwar in der Plattform selbst: über die externe API ist ein versteckter Fall weder setzbar noch auffindbar (404).
  • 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ÜbergangRequest-BodyServer-Guard
FreigebenWORK_IN_PROGRESS → RELEASED{"status":"RELEASED"}signierte Vollmacht/RKÜ (außer Eigenbearbeitung)
An Gutachter übergebenWORK_IN_PROGRESS/RELEASED → HANDED_OVER_APPRAISER{"status":"HANDED_OVER_APPRAISER"}signierter Gutachtenauftrag + Vollmacht
Übergabe zurücknehmen (Force-Release)HANDED_OVER_APPRAISER → RELEASED{"status":"RELEASED"}Rolle USP_ADMIN der Grant-Person
AbschließenWORK_IN_PROGRESS/RELEASED/HANDED_OVER_APPRAISER → CLOSED{"status":"CLOSED"}Fallabwickler-/Admin-Recht; bei Eigenbearbeitung auch Personen des Fallstandorts (nicht das Gutachterbüro)
WiedereröffnenCLOSED/CANCELLED → reopenTarget des Falls (RELEASED, HANDED_OVER_APPRAISER oder WORK_IN_PROGRESS){"status":"<reopenTarget>"}aus CLOSED: Fallabwickler (inkl. Betreiber), USP_ADMIN allein genügt nicht; jedes andere Ziel als reopenTarget oder WORK_IN_PROGRESS ⇒ 409
Wiedereröffnen in BearbeitungCLOSED/CANCELLED → WORK_IN_PROGRESS (immer möglich){"status":"WORK_IN_PROGRESS"}aus CLOSED: Fallabwickler (inkl. Betreiber)
Storniereneditierbarer Fall → CANCELLED{"status":"CANCELLED","reason":"…"}reason ist Pflicht
Fortschritt markierenkein 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://usp.linkki.de/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​

ZielstatusZeitstempelMailBenachrichtigung
RELEASED (aus WORK_IN_PROGRESS)releaseDate gesetztCASE_RELEASED an den Fallabwickler-Standort (je nach Mail-Präferenz; unterdrückt bei Eigenbearbeitung)ja
RELEASED (Wiedereröffnen)releaseDate neu, closedDate/cancelledDate geleertkeine Freigabe-Mail—
WORK_IN_PROGRESS / HANDED_OVER_APPRAISER (Wiedereröffnen)closedDate/cancelledDate/releaseDate geleertkeine—
HANDED_OVER_APPRAISER—keinekeine; nach dem Commit läuft die Übergabe ans Gutachtersystem
CLOSEDclosedDate gesetztkeine (es gibt bewusst keine Abschluss-Mail)CASE_CLOSED
CANCELLEDreleaseDate geleertkeinekeine

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)
DELETE /api/external/v1/cases/{caseId}/tags/{tag} (Scope cases:write)
curl -sS -X PUT https://usp.linkki.de/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" } ]
WertBedeutung
LIABILITY_CONFIRMATION_ISSUEDDie gegnerische Versicherung hat die Haftung bestätigt
RENTAL_CAR_PRICE_INFORMATION_RECEIVEDMietwagen-Preisinformation liegt vor
ADVANCE_RECEIVEDVorschuss ist eingegangen
NONEPlatzhalter — wird mit 400 VALIDATION abgelehnt

Ein versehentlich gesetzter Tag lässt sich wieder entfernen — der Tag steht dabei im Pfad, nicht im Body:

curl -sS -X DELETE https://usp.linkki.de/api/external/v1/cases/$CASE_ID/tags/LIABILITY_CONFIRMATION_ISSUED \
-H "Authorization: Bearer $USP_API_KEY"

Eigenschaften:

  • Idempotent in beide Richtungen: ein bereits vorhandener Tag beim Setzen und ein nicht vorhandener beim Entfernen sind jeweils ein No-Op, kein Fehler. Doppelte Aufrufe sind für eine Integration normal und ausdrücklich erlaubt.
  • Ein unbekannter Tag-Wert im Pfad ergibt 400 VALIDATION (kein Framework-400 ohne code).
  • 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?​

HTTPcodeWannWas tun
400VALIDATIONstatus fehlt, status=HIDDEN, Storno ohne reason, tag fehlt oder ist NONE, ungültige UUIDRequest korrigieren
403ACCESS_DENIEDKey ohne cases:status/cases:write; oder der Übergang verlangt Fallabwickler-/Admin-Rechte, die die Grant-Person nicht hat (auch HANDED_OVER_APPRAISER → RELEASED ohne USP_ADMIN)Scopes prüfen; Aktion einer berechtigten Person überlassen
404NOT_FOUNDFall unbekannt, fremder Mandant oder außerhalb der SichtbarkeitcaseId prüfen
409CONFLICTFreigabe ohne signierte Vollmacht; Übergabe ohne Gutachtenauftrag/Vollmacht; Wechsel nach/aus WAITING_FOR_CUSTOMER; Wiedereröffnen in ein anderes Ziel als reopenTarget oder WORK_IN_PROGRESS; Fall beim Schreiben der Storno-Begründung nicht editierbarfehlendes Dokument abwarten; beim Wiedereröffnen reopenTarget des Falls lesen; bei Storno erst wiedereröffnen
429RATE_LIMITED / API_RATE_LIMITEDRate-Limit erreichtRetry-After abwarten

Sequenzdiagramm​