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://dev.devlodge.site/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.

Zwei bewusste Einschränkungen

@-Erwähnungen sind gesperrt. Enthält dein Text ein Token, das sich auf eine_n Beteiligte_n des Falls auflösen würde (Standort- oder Partner-Mitglied, Fallabwickler-Code, Gutachterbüro-Code), lehnt der Server den Request mit 400 VALIDATION ab:

{ "code": "VALIDATION", "message": "Kommentare ueber die externe API duerfen keine @-Erwaehnungen von Beteiligten enthalten" }

Der Text wird dabei nicht stillschweigend verändert — eine automatische Bereinigung wäre eine Verfälschung deiner Nachricht. Tokens, die sich ohnehin nicht auflösen (etwa eine Mailadresse im Text), passieren unverändert und benachrichtigen niemanden.

Der Grund: eine Integration kennt die Personen hinter den Namen nicht und kann die Folgen einer Erwähnung — persönliche Sofort-Mails an Menschen, die sie nie ausgewählt hat — nicht beurteilen. Willst du gezielt jemanden erreichen, nenn die Person im Fließtext („bitte an Frau Meier") statt mit @.

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

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.

Noch nicht verfügbar

Fähigkeit	Stand
Kommentar bearbeiten	existiert extern nicht
Kommentar löschen	existiert plattformweit nicht — Kommentare sind unlöschbar
Kommentar für die Kund_in freigeben (customerVisible)	existiert extern nicht
@-Erwähnungen auslösen	bewusst gesperrt (siehe oben)
Beteiligte eines Falls auflisten (Mention-Ziele)	existiert extern nicht; die Kolleg_innen des Mandanten liefert GET /users, siehe Stammdaten

Was kann schiefgehen?

HTTP	code	Wann	Was tun
400	VALIDATION	Text fehlt oder ist leer	nicht-leeren Text senden
400	VALIDATION	Text enthält eine auflösbare @-Erwähnung	Erwähnung entfernen, Person im Fließtext nennen
403	ACCESS_DENIED	Key ohne comments:read bzw. comments:write	Key-Scopes prüfen
404	NOT_FOUND	Fall unbekannt, fremder Mandant oder außerhalb der Sichtbarkeit	caseId 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