> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mitarbeitervorfälle verwalten

> Erstellen Sie Vorfälle, synchronisieren Sie den serververwalteten Lifecycle-Status, aktualisieren Sie unterstützte Datumsfelder und laden Sie zulässige Nachweisdateien hoch.

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

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Source as HR- / Quellprozess
    participant INT as Integration
    participant API as JobHandy API
    participant STORE as JobHandy-Vorfallsspeicher

    Source->>INT: Vorfallsdaten
    INT->>API: POST /incidents?dryRun=true
    API-->>INT: Projizierter Vorfall
    INT->>API: POST /incidents
    API->>STORE: Vorfall speichern und Melder/Status zuweisen
    API-->>INT: Erstellter Vorfall + Request-ID
    loop Lifecycle synchronisieren
        INT->>API: GET /incidents/{id}
        API-->>INT: Aktueller serververwalteter Status und Datumsfelder
    end
    opt Unterstützte Felder aktualisieren
        INT->>API: PATCH /incidents/{id}?dryRun=true
        API-->>INT: Projizierter Vorfall
        INT->>API: PATCH /incidents/{id}
    end
    opt Bearbeitbarer abgeschlossener Vorfall erlaubt Anhänge
        INT->>API: POST /incidents/{id}/attachments
        API-->>INT: Aktualisiertes Ergebnis
    end
```

## Vorfall erstellen

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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, antwortet `POST /incidents` mit `422 EMPLOYEE_NOT_ACTIVATED`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "EMPLOYEE_NOT_ACTIVATED",
    "message": "The referenced employee is not activated.",
    "requestId": "<Request-UUID v4 oder v7>"
  }
}
```

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    A[Create-Anfrage für Vorfall] --> B{Mitarbeiter aktiviert?}
    B -- Nein --> C[422 EMPLOYEE_NOT_ACTIVATED]
    C --> D[Mitarbeiteraktivierung abschließen]
    D --> E[Neue Anfrage mit neuer X-Request-ID senden]
    B -- Ja --> F[Vorfall validieren und erstellen]
```

Die Anfrage darf erst nach der Aktivierung des Mitarbeiters erneut gesendet werden.

## 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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "dateUntil": "2026-09-02T00:00:00.000Z"
}
```

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

## Bedingungen für Anhänge

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    A[Vorfall lesen] --> B{Abgeschlossen und bearbeitbar?}
    B -- Nein --> X[Nicht hochladen]
    B -- Ja --> C[Dateianzahl, Medientyp und Gesamtgröße prüfen]
    C --> D[Upload mit dryRun=true]
    D --> E{Gültig?}
    E -- Nein --> F[Dateien korrigieren]
    E -- Ja --> G[Upload ohne Dry Run]
    G --> H[Request-ID und Ergebnis speichern]
```

## 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_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                                     |