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

# API-Changelog

> Verfolgen Sie Änderungen an API und Schemas, Auswirkungen auf Clients, Deprecations und Migrationsanforderungen.

Die JobHandy Public API bleibt auf dem Basispfad `/v1` in Version `1.0.0`.

## 02.09.2026 – 1.0.0

### Vorfälle

* `POST /incidents` antwortet nun mit `422 EMPLOYEE_NOT_ACTIVATED`, wenn der referenzierte Mitarbeiter im autorisierten Scope existiert, seine Aktivierung aber noch nicht abgeschlossen ist.
* Die Fehlermeldung lautet `The referenced employee is not activated.`
* Bei dieser Validierung wird kein Vorfall erstellt.

### Auswirkungen auf Clients

Wiederholen Sie dieselbe Create-Anfrage nicht, solange die Mitarbeiteraktivierung noch nicht abgeschlossen ist. Senden Sie nach der Aktivierung eine neue Anfrage mit einer neuen `X-Request-ID`.

## 28.08.2026 – 1.0.0

### Bestellungen

* `tenant` und `divisionId` wurden aus dem `Order`-Response-Schema entfernt.
* `hrReviewDecision` und `OrderHrReviewDecision` wurden durch `hrHistory` und `OrderHrHistory` ersetzt.
* `hrHistory.decisionBy` enthält nun eine nullable 24-stellige Benutzer-ID. Bei automatisierten Entscheidungen und Entscheidungen per API-Schlüssel ist der Wert `null`.
* Das in `products[]` von `GET /orders`, `GET /orders/{id}` und `POST /orders/{id}/decision` zurückgegebene `OrderProduct`-Modell wurde ersetzt.
* `OrderProduct` enthält nun `model`, `vatRate`, `manufacturerName`, `articleGroupName`, `grossAmount`, `netAmount`, `service`, `grossService` und `netService`.
* `description`, `rateInCents` und `serviceRateInCents` wurden aus `OrderProduct` entfernt.
* `model`, `manufacturerName`, `articleGroupName`, `service`, `grossService` und `netService` sind nullable.
* `vatRate` und `grossAmount` sind Dezimalzeichenfolgen mit zwei Nachkommastellen; `netAmount` verwendet vier Nachkommastellen. `grossService` und `netService` sind nullable Dezimalzeichenfolgen mit zwei Nachkommastellen.

### Order-Abfragen

* `tenant` und `divisionId` wurden aus den unterstützten Filter- und Sortierfeldern von `GET /orders` entfernt.
* Verwenden Sie bei Bedarf `X-Tenant-ID`, um eine Order-Abfrage auf einen autorisierten Tenant einzuschränken.

### Divisionen

* `Division.order`, `DivisionCreate.order` und `DivisionPatch.order` wurden vom OpenAPI-Typ `integer` auf `number` geändert.
* Die bisherige Integer-Beschränkung `multipleOf: 1` wurde entfernt.

### Auswirkungen auf Clients

Die API-Version bleibt `1.0.0` und die produktive Basis-URL bleibt `https://api.jobhandy.io/v1`. Clients, die Order-Responses deserialisieren, müssen ihre Modelle, DTOs, Mappings, Dezimalverarbeitung, Mocks und Contract Tests aktualisieren. Leiten Sie Tenant oder Division nicht aus Feldern ab, die nicht mehr in der `Order`-Response enthalten sind.

## Ursprünglicher öffentlicher Funktionsumfang

### Verfügbare Ressourcen

* Mitarbeiter: auflisten, erstellen, abrufen, aktualisieren
* Bestellungen: auflisten, abrufen, HR-Entscheidung, Attachment-Download
* Vorfälle: auflisten, erstellen, abrufen, aktualisieren, Attachment-Upload
* Divisionen: auflisten, erstellen, abrufen, aktualisieren
* Payroll-Exportdokumente: auflisten, abrufen, herunterladen
* Health: öffentliche Verfügbarkeitsprüfung

### Übergreifendes Verhalten

* Authentifizierung über `X-API-Key`
* optionale Tenant-Auswahl über `X-Tenant-ID`, wo dokumentiert
* Korrelation über UUID-v4/v7-`X-Request-ID`
* seitenbasierte Collection-Pagination
* Sortierung nach einem Feld
* Filterausdruckssprache
* Dry-Run-Validierung bei unterstützten Schreibvorgängen
* einheitliches strukturiertes Fehler-Envelope
* Rate-Limit-Response-Header

<Note>
  Das OpenAPI-Dokument enthält kein Veröffentlichungsdatum für diesen Ausgangsstand. Zukünftige Einträge sollen ein ausdrückliches Releasedatum und die Migrationsauswirkungen enthalten.
</Note>

## Format zukünftiger Einträge

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
## YYYY-MM-DD - Vertragsversion

### Hinzugefügt
### Geändert
### Korrigiert
### Veraltet
### Entfernt
### Sicherheit
### Migration
```

## Verantwortung des Clients

Vor der Übernahme einer neuen OpenAPI-Datei:

1. Mit der derzeit vom Client verwendeten Version vergleichen.
2. Änderungen an Requests, Responses, Schemas, Enums, Endpoints und Fehlern ermitteln.
3. Client-Typen neu erzeugen oder aktualisieren.
4. Vertrags- und Abnahmetests ausführen.
5. Übernommene Version und Prüfsumme dokumentieren.

<Card title="Versionierungsrichtlinie" icon="git-branch" horizontal href="/de/concepts/versioning">
  Prüfen Sie, welche Änderungen additiv sind und welche eine Migration erfordern.
</Card>