Mitarbeitervorfälle verwalten

API 2.0.0: Aktiver Vertrag erforderlich

POST /incidents erfordert einen Vertrag mit Status active. Der Status approved reicht nicht aus. Ohne aktiven Vertrag scheitert die Anfrage mit HTTP 422 und EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, auch bei dryRun=true; es wird kein Vorfall erstellt. Klären Sie den Vertragsstatus über den zuständigen Fachprozess, bevor Sie eine neue Anfrage mit neuer X-Request-ID senden. Bestehende Vorfälle bleiben unter ihren bisherigen Lebenszyklus- und Feldbeschränkungen bearbeitbar. Die neue Voraussetzung gilt für das Erstellen. Die Voraussetzung der Mitarbeiteraktivierung bleibt separat dokumentiert; eine Reihenfolge der Validierungsfehler ist nicht festgelegt. Die Incidents API unterstützt das Melden von Mitarbeitervorfällen, Lesen des Lifecycle-Status, Aktualisieren dokumentierter bearbeitbarer Felder und Hochladen zulässiger Anhänge.

Typen und Statuswerte

Dimension	Werte	Verantwortlichkeit
Typ	`temporary`, `permanent`	Wird beim Create gesetzt; Updates nur wie dokumentiert
Status	`reported`, `in_progress`, `completed`, `archived`	Serverseitig verwaltet
Melder	`user`, `api_key`	Serverseitig zugewiesen

Der öffentliche Vertrag stellt den Status zum Lesen bereit, bietet im Patch-Schema jedoch kein frei beschreibbares Statusfeld an.

Statusverantwortung

Status	Direkte Statusänderung über Public Patch	Attachment-Upload
`reported`	Nein; Status wird serverseitig verwaltet	Nein
`in_progress`	Nein; Status wird serverseitig verwaltet	Nein
`completed`	Nein; Status wird serverseitig verwaltet	Nur unterstützt, wenn der Vorfall bearbeitbar ist
`archived`	Nein; Status wird serverseitig verwaltet	Nein

Der öffentliche Vertrag stellt in IncidentPatch keine generische Eigenschaft status bereit. Synchronisieren Sie den Status, indem Sie den Vorfall lesen.

Swimlane für Vorfälle

Vorfall erstellen

{
  "type": "temporary",
  "employee": "690000000000000000000001",
  "dateFrom": "2026-08-26T00:00:00.000Z"
}

Der referenzierte Mitarbeiter muss im ausgewählten Tenant-Kontext zugänglich und bereits aktiviert sein. Die API setzt Meldermetadaten und initialen Lifecycle-Status. Existiert der Mitarbeiter, wurde aber noch nicht aktiviert, kann POST /incidents mit 422 EMPLOYEE_NOT_ACTIVATED antworten:

{
  "error": {
    "code": "EMPLOYEE_NOT_ACTIVATED",
    "message": "The referenced employee is not activated.",
    "requestId": "<Request-UUID v4 oder v7>"
  }
}

Bei EMPLOYEE_NOT_ACTIVATED muss die Aktivierung abgeschlossen werden. Bei EMPLOYEE_HAS_NO_ACTIVE_CONTRACT muss ein aktiver Vertrag vorliegen. Vor einer neuen Create-Anfrage muessen beide Voraussetzungen erfuellt sein; die Reihenfolge der Validierungsfehler ist nicht festgelegt.

Unterstützte Felder aktualisieren

Der Patch-Vertrag stellt type, dateFrom und dateUntil bereit. Das Setzen von dateUntil beendet einen offenen temporären Vorfall oder plant dessen Abschluss entsprechend den serverseitigen Regeln.

{
  "dateUntil": "2026-09-02T00:00:00.000Z"
}

Vorfälle können über diesen Endpoint nicht wiedereröffnet werden.

Bedingungen für Anhänge

POST /incidents/{id}/attachments
Content-Type: multipart/form-data
field: uploads

Einschränkung	Vertrag
Vorfallsstatus	Bearbeitbarer abgeschlossener Vorfall
Dateianzahl	1 bis 5
Akzeptierte Inhalte	`image/*` oder `application/pdf`
Vollständiger Multipart-Body	Maximal 5 MiB
Dry Run	Validiert, ohne Dateien zu speichern

Das Limit von 5 MiB gilt für den codierten vollständigen Multipart-Request einschließlich Boundaries und Headern.

Upload-Ablauf

Datenminimierung

Laden Sie ausschließlich Dokumente hoch, die für den Vorfallsprozess erforderlich sind. Fügen Sie keine sachfremden personenbezogenen Daten hinzu und schützen Sie lokale Quelldateien, Retry-Queues und heruntergeladene Nachweise entsprechend den Aufbewahrungs- und Zugriffsregeln des Kunden.

Häufige Fehler

Fehler	Ursache	Maßnahme
`EMPLOYEE_NOT_ACTIVATED`	Referenzierter Mitarbeiter wurde noch nicht aktiviert	Mitarbeiter aktivieren und anschließend eine neue Create-Anfrage senden
`EMPLOYEE_HAS_NO_ACTIVE_CONTRACT`	422: Vertrag nicht `active`; auch bei Dry Run	Vertragsstatus fachlich klären
`EMPLOYEE_BLOCKED`	Mitarbeiterstatus verhindert die Operation	Mitarbeiterstatus und Fachprozess prüfen
`INVALID_STATE_TRANSITION`	Vorfall kann die angeforderte Änderung nicht annehmen	Aktuellen Lifecycle-Status erneut lesen
`MISSING_ATTACHMENT`	Multipart-Feld fehlt	Eine oder mehrere Dateien im Feld `uploads` hinzufügen
`PAYLOAD_TOO_LARGE`	Vollständiger Body überschreitet 5 MiB	Dateianzahl oder Dateigröße reduzieren
`UNSUPPORTED_MEDIA_TYPE`	Datei- oder Request-Medientyp wird nicht akzeptiert	Dokumentierte Medientypen verwenden

Erste Schritte

Architektur & Konzepte

Integrationsleitfäden

Betrieb

API 2.0.0: Aktiver Vertrag erforderlich

Typen und Statuswerte

Statusverantwortung

Swimlane für Vorfälle

Vorfall erstellen

Unterstützte Felder aktualisieren

Bedingungen für Anhänge

Upload-Ablauf

Datenminimierung

Häufige Fehler

​API 2.0.0: Aktiver Vertrag erforderlich

​Typen und Statuswerte

​Statusverantwortung

​Swimlane für Vorfälle

​Vorfall erstellen

​Unterstützte Felder aktualisieren

​Bedingungen für Anhänge

​Upload-Ablauf

​Datenminimierung

​Häufige Fehler

API 2.0.0: Aktiver Vertrag erforderlich

Typen und Statuswerte

Statusverantwortung

Swimlane für Vorfälle

Vorfall erstellen

Unterstützte Felder aktualisieren

Bedingungen für Anhänge

Upload-Ablauf

Datenminimierung

Häufige Fehler