Fallanlage

Ziel

Du willst wissen, wie ein Fall entsteht, wie deine Integration selbst einen anlegt und wie sie mitbekommt, dass es neue Fälle gibt.

Wie Fälle entstehen

Weg	Wer	Ergebnisstatus
Fallformular in der Oberfläche	Standort-Nutzer_in, Fallabwickler_in, Gutachter_in, Admin	WORK_IN_PROGRESS
Tally-Webhook (Online-Schadenformular des Standorts)	Kund_in bzw. Standort	WORK_IN_PROGRESS
Kundenportal „Kunde hilft mit" (sofern für den Standort verfügbar)	Plattform bei der Einladung	WAITING_FOR_CUSTOMER, nach Portal-Freigabe WORK_IN_PROGRESS
Externe API: POST /api/external/v1/cases	Integration (Werkstatt-, Fallabwickler-, Gutachter- oder Admin-Mandant)	WORK_IN_PROGRESS

Ein neuer Fall trägt in allen Fällen mindestens locationId (Standort) und damageType (THIRD_PARTY_LIABILITY oder OWN_FAULT); der Fallabwickler (caseHandler) wird serverseitig aus dem Standort abgeleitet. Alles Weitere kann leer sein — genau das ist typischerweise die Lücke, die deine Integration füllt.

Fall per API anlegen

Sicht: Werkstatt · Fallabwickler · Gutachterbüro (· Admin) — jede Sicht mit eigener Regel, siehe Tabelle unten.

POST /api/external/v1/cases          (Scope cases:write)

Die Anlage läuft durch denselben internen Pfad wie das Fallformular der Plattform: der Server leitet den Fallabwickler aus locationId + damageType ab, startet die Fallhistorie und benachrichtigt wie bei jeder anderen Anlage. Antwort ist 201 mit dem vollständigen Fall — inklusive der serververgebenen id und dem ersten lastModifiedDate (deine Baseline für das erste PUT).

curl -sS -X POST "$USP_BASE/cases" \
  -H "Authorization: Bearer $USP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "locationId": "musterhaus",
        "damageType": "THIRD_PARTY_LIABILITY",
        "vehicleLicensePlate": "B-XY 123",
        "injuredParty": { "firstName": "Erika", "lastName": "Musterfrau" }
      }' | jq '{id, status, caseHandler, lastModifiedDate}'

Die Regeln:

Regel	Verhalten
Der neue Fall muss zum Mandanten deines Keys gehören	Werkstatt-Key: locationId liegt im eigenen Teilbaum. Fallabwickler-Key: das Routing aus locationId + damageType landet bei dir — du legst genau dort an, wo Standort und Schadenart dir zugeordnet sind (nie OWN_PROCESSING, das hat kein Routing). Gutachter-Key: dem Standort ist dein Büro als Gutachter zugewiesen — dein Büro ist am neuen Fall dann automatisch als Gutachter (expertOfficeCode) vorausgewählt. Admin-Mandant: keine Teilbaum-Schranke. Alles andere ist 404 NOT_FOUND
Die Person hinter dem Grant muss für den Standort berechtigt sein	sonst 403 ACCESS_DENIED
Startstatus ist fix WORK_IN_PROGRESS	ein anderer status im Rumpf ist 400 — Statuswechsel laufen danach über PUT /cases/{caseId}/status samt aller Guards
Die id vergibt der Server	eine id im Rumpf ist 400
damageType ist Pflicht (außer OWN_PROCESSING)	sonst 400 — ohne Schadenart kann das Fallabwickler-Routing nicht auflösen
Routing-/Lifecycle-Felder sind server-managed	caseHandler, expertOfficeCode, closedDate, releaseDate, externalId, tallyResponseId aus dem Rumpf werden verworfen
OWN_PROCESSING verlangt Admin-Rechte	wie in der Plattform: USP_ADMIN-Rolle + ein Standort mit erlaubter Eigenabwicklung, sonst 403
Kein Fallabwickler für Standort+Schadenart konfiguriert	400 VALIDATION — der Standort ist dann fachlich nicht fertig eingerichtet

Fälle im Status WAITING_FOR_CUSTOMER erscheinen in deiner Liste, sind aber nicht editierbar: solange die Kund_in am Portal arbeitet, antwortet PUT /cases/{caseId} mit 409. Warte, bis der Fall auf WORK_IN_PROGRESS wechselt.

Neue Fälle finden

Der empfohlene Weg: Delta-Abholung

GET /api/external/v1/cases?changedSince=2026-07-20T06:00:00      (Scope cases:read)

Liefert unpaginiert alle Fälle des Mandanten, deren lastModifiedDate am oder nach dem Zeitstempel liegt, älteste Änderung zuerst. Neu angelegte Fälle sind darin automatisch enthalten — ihre Anlage ist ihre erste Änderung. Details, Grenzen und die Zeitstempel-Fortschreibung stehen unter Übersicht und Bearbeitung und im Integrator-Kochbuch.

Der Weg für den Erstabgleich: seitenweise nach Anlagedatum

GET /api/external/v1/cases?sort=CREATION_DATE&direction=ASC&page=0&size=200

Beim initialen Befüllen deines Zielsystems willst du chronologisch von vorne durchlaufen. size ist auf 200 gedeckelt; blättere über page, bis page + 1 == totalPages.

Das Feld opened jedes Listeneintrags ist der Anlagezeitpunkt, updated der aus der Fallhistorie abgeleitete Änderungszeitpunkt.

Was du an einem frischen Fall tun kannst

Absicht	Endpunkt	Scope
Vollständige Falldaten lesen	GET /cases/{caseId}	cases:read
Felder ergänzen (Aktenzeichen, IBAN, Unfalldaten …)	PUT /cases/{caseId}	cases:write
Dokumente anhängen	POST /cases/{caseId}/attachments	attachments:write
Dokumente klassifizieren	PUT /attachments/{attachmentId}/tag	attachments:write
Sachstand kommentieren	POST /cases/{caseId}/comments	comments:write
Fortschritt markieren	PUT /cases/{caseId}/tags	cases:write
Freigeben / abschließen / stornieren	PUT /cases/{caseId}/status	cases:status

Für das Zurückschreiben gilt die Optimistic-Lock-Regel: lies den Fall, ändere die Felder am gelesenen Objekt, schicke es komplett zurück — inklusive lastModifiedDate und locationId. Siehe Übersicht und Bearbeitung.

Noch nicht verfügbar

Fähigkeit	Stand
Fahrzeugschein-Scan / KI-Extraktion	existiert extern nicht. Der Scope extraction:execute ist im Katalog reserviert, aber kein Endpunkt nutzt ihn
Vollmacht/RKÜ, Gutachtenauftrag oder Reparaturablaufplan erzeugen	existiert extern nicht
Dokumente signieren oder an die Kund_in senden	existiert extern nicht
Fallhistorie lesen	existiert extern nicht
Kundenportal steuern	existiert extern nicht

Der einzige verlässliche Weg, an Dokumente eines Falls zu kommen, ist deshalb die Anhangsliste: Anhänge verwalten.

Sequenzdiagramm