Zum Hauptinhalt springen
Die aktuelle Vertragsversion der JobHandy Public API ist 2.0.0. Die dokumentierte produktive Basis-URL bleibt https://api.jobhandy.io/v1.

​
2.0.0 – Breaking Change

Diese Version ist mit Integrationen auf Basis von 1.0.0 nicht vollständig abwärtskompatibel. Die Request-Felder bleiben gleich; die Verarbeitung und Validierung ändern sich.

​
Vorfälle

  • POST /incidents erfordert einen Vertrag im Status active; approved reicht nicht.
  • Ohne aktiven Vertrag: HTTP 422 mit EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, auch bei dryRun=true.
  • Bestehende Vorfälle bleiben bearbeitbar.

​
Mitarbeiter

  • Bei aktivem Vertrag sind sowohl blocked: true als auch blocked: false bei PATCH /employees/{id} unzulässig.
  • Die API lehnt den gesamten Patch mit HTTP 422 und EMPLOYEE_HAS_ACTIVE_CONTRACT ab, auch bei dryRun=true. Andere Felder werden nicht teilweise übernommen.

​
Migration

Lassen Sie blocked bei reinen Profiländerungen vollständig weg, einschließlich automatisch ergänzter Standardwerte. Aktualisieren Sie Vertragsprüfungen, Fehlerbehandlung, Mappings und Tests für beide Schreiboperationen und Dry Runs. Wiederholen Sie fachlich abgelehnte Requests nicht unverändert. Vollständige Migrationshinweise.

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

​
Format zukünftiger Einträge

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

Versionierungsrichtlinie

Prüfen Sie, welche Änderungen additiv sind und welche eine Migration erfordern.
Zuletzt geändert am 20. Oktober 2026