Kommentare

Ziel

Du liest den Kommentarverlauf eines Falls und hängst eigene Sachstandsmeldungen an — der einfachste Weg, Menschen in der Plattform über etwas zu informieren, das in deinem System passiert ist („Klage eingereicht", „Fahrzeug angeliefert", „Zahlung eingegangen").

Voraussetzungen

• Scopes: comments:read zum Lesen, comments:write zum Schreiben (beide Risikostufe „normal").
• Sichtbarkeit: Der Fall muss im Mandanten des Keys liegen und für die Grant-Person sichtbar sein — sonst 404.
• Status: keiner. Kommentare sind in jedem Fallstatus erlaubt, auch auf abgeschlossenen und stornierten Fällen.

1. Kommentare lesen

GET /api/external/v1/cases/{caseId}/comments        (Scope comments:read)

Liefert alle Kommentare des Falls, sortiert nach dem letzten Änderungszeitpunkt:

Feld	Inhalt
commentId	UUID des Kommentars
createdBy	Benutzername des Autors bzw. der Autorin (SYSTEM bei Systemeinträgen)
fullName	Anzeigename, pro Abruf live aus dem Identity-Provider aufgelöst
creationDate	Erstellzeitpunkt
comment	Nachrichtentext
customerVisible	true, wenn der Text der Kund_in im Kundenportal gezeigt wird
customerAuthored	true bei Kommentaren, die die Kund_in im Portal geschrieben hat (Autor-Label „Kund_in (extern)")

Du bekommst den kompletten Verlauf: interne Kommentare, für die Kund_in freigegebene und von der Kund_in geschriebene. Im Text können @…-Tokens stehen — sie sind Klartext, du musst sie nicht auflösen.

2. Kommentar anhängen

POST /api/external/v1/cases/{caseId}/comments        (Scope comments:write)

curl -sS -X POST https://usp.linkki.de/api/external/v1/cases/$CASE_ID/comments \
  -H "Authorization: Bearer $USP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment":"Klage beim Amtsgericht eingereicht, Az. 12 C 345/26."}'

Der Body kennt genau ein Feld: comment. Autor, Zeitstempel und die Kunden-Sichtbarkeit setzt der Server; alles andere, was du mitschickst, wird ignoriert.

Antwort: 201 Created mit dem gespeicherten CommentDTO.

Was passiert danach:

• Der Kommentar wird unter der Identität der Person gespeichert, zu der der Grant deines Keys gehört — nicht unter einem anonymen Systemnamen. In der Oberfläche steht also ein echter Name.
• Es entsteht ein Fallhistorie-Eintrag (und damit bewegt sich lastModifiedDate des Falls, siehe unten).
• Der Fallabwickler-Standort bekommt eine Benachrichtigung und, abhängig von seiner Mail-Präferenz und vom Fallstatus, die Mail COMMENT_ADDED. Im Entwurfsstatus (WORK_IN_PROGRESS) unterbleibt der Mailversand.

@-Erwähnungen

Erwähnungen funktionieren exakt wie in der Plattform: ein Token wie @maxmuster wird gegen die Beteiligten des Falls aufgelöst (Standort- und Partner-Mitglieder, Fallabwickler-Code, Gutachterbüro-Code). Aufgelöste Erwähnungen erzeugen eine Benachrichtigung und — je nach persönlicher Mail-Präferenz — eine persönliche Mail an die erwähnte Person. Tokens, die sich nicht auflösen (etwa eine Mailadresse im Text), passieren unverändert und benachrichtigen niemanden.

Die erwähnbaren Benutzernamen liefert GET /users (Stammdaten); Fallabwickler und Gutachterbüro stehen als Codes am Fall (caseHandler, expertOfficeCode).

Dieselbe Liste löst auch den Autor eines gelesenen Kommentars auf: createdBy ist der Benutzername, und directColleague sagt dir, ob die Person zu deinem Mandanten gehört oder zur Gegenseite (Werkstatt bzw. Gutachterbüro). Wer im Fremdsystem nur für fremde Beiträge benachrichtigen will, braucht dafür keinen Standortcode.

Die Rollenwörter @fallabwickler und @gutachter

Statt den Standortcode nachzuschlagen, kannst du die beiden Rollen direkt beim Namen nennen:

Token	Adressiert
@fallabwickler	den Fallabwickler des Falls (caseHandler)
@gutachter	das zugewiesene Gutachterbüro (expertOfficeCode)

Der Server schreibt sie beim Speichern auf den echten Standortcode um. Liest du den Kommentar danach zurück, steht dort also @musterhandler, nicht @fallabwickler — der gespeicherte Text und die daraus entstandene Benachrichtigung sagen dasselbe. Groß-/Kleinschreibung ist egal.

Hat der Fall für die Rolle keinen Standort (kein Gutachter zugewiesen), bleibt das Token unverändert stehen und benachrichtigt niemanden — wie jedes andere nicht auflösbare Token.

Nur auf dieser API

Die Plattform-Oberfläche kennt die Rollenwörter nicht: dort bietet das Mention-Dropdown beide Gruppen mit Namen an, ihre Nutzer_innen müssen den Code also nie kennen. Zwei Schreibweisen für dasselbe Ziel gäbe es dort ohne Gewinn.

Extern erzeugte Kommentare sind immer intern. customerVisible ist fest false und im Request-Body gar nicht vorgesehen. Einen Text für die Kund_in freizugeben bleibt der Oberfläche vorbehalten.

3. Eigenen Kommentar bearbeiten

PUT /api/external/v1/comments/{commentId}        (Scope comments:write)

curl -sS -X PUT https://usp.linkki.de/api/external/v1/comments/$COMMENT_ID \
  -H "Authorization: Bearer $USP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment":"Korrektur: Az. lautet 12 C 346/26."}'

Ersetzt den Nachrichtentext — nur bei eigenen Kommentaren (die Autor_in ist die Person, zu der der Grant deines Keys gehört; dieselbe Regel wie in der Plattform). Ein fremder Kommentar antwortet 403 ACCESS_DENIED, ein Kommentar außerhalb des Mandanten 404. Autor-Metadaten und customerVisible bleiben unverändert; @-Erwähnungen werden gegen den neuen Text neu aufgelöst. Auch die Bearbeitung schreibt einen Fallhistorie-Eintrag und löst die Standort-Mail COMMENT_UPDATED aus (je nach Präferenz). Kommentare löschen gibt es plattformweit nicht.

Achtung: Optimistic Lock

Ein Kommentar schreibt einen Fallhistorie-Eintrag und schiebt damit lastModifiedDate des Falls vor. Ein danach abgesetztes PUT /cases/{caseId} mit dem alten Zeitstempel scheitert mit 400 ALREADY_MODIFIED — also entweder erst den Fall schreiben und dann kommentieren, oder nach dem Kommentar den Fall neu lesen. Siehe Übersicht und Bearbeitung.

Was kann schiefgehen?

HTTP	code	Wann	Was tun
400	VALIDATION	Text fehlt oder ist leer	nicht-leeren Text senden
403	ACCESS_DENIED	Key ohne comments:read bzw. comments:write — oder Bearbeiten eines fremden Kommentars	Key-Scopes prüfen; nur eigene Kommentare bearbeiten
404	NOT_FOUND	Fall/Kommentar unbekannt, fremder Mandant oder außerhalb der Sichtbarkeit	IDs prüfen
429	RATE_LIMITED / API_RATE_LIMITED	Rate-Limit erreicht	Retry-After abwarten
500	INTERNAL_ERROR	unerwarteter Serverfehler	errorId an den Support geben

Sequenzdiagramm