Zum Hauptinhalt springen

​
API 2.0.0: Sperränderungen bei aktiven Verträgen

Bei PATCH /employees/{id} verbietet ein aktiver Vertrag sowohl blocked: true als auch blocked: false. Enthält die Anfrage blocked, lehnt die API den gesamten Patch mit HTTP 422 und EMPLOYEE_HAS_ACTIVE_CONTRACT ab, auch bei dryRun=true. Andere Felder dieser abgelehnten Anfrage werden nicht übernommen. Auch das erneute Senden des bereits gespeicherten blocked-Werts ist unzulässig. Für reine Profiländerungen lassen Sie blocked vollständig weg. Konfigurieren Sie Serialisierung und Synchronisationsmapping so, dass blocked: false nicht als Standardwert hinzugefügt wird. Beispiel:
Wiederholen Sie einen unveränderten abgelehnten Patch nicht. Klären Sie den Sperrauftrag über den zuständigen Fachprozess oder senden Sie für eine unabhängig beabsichtigte Profiländerung einen neuen Patch ausschließlich mit den gewünschten unterstützten Profilfeldern. Ein erfolgreicher Dry Run reserviert den Vertragsstatus nicht; behandeln Sie dieselbe Validierung beim realen Schreibvorgang. Mitarbeiter sind kundenspezifische Stammdatenressourcen. Die Public API unterstützt Auflisten, Erstellen, Abrufen und partielle Aktualisierung.

​
Funktionen

​
Lifecycle

​
Endpoints

Mitarbeiter auflisten

Mitarbeiter-Collections paginieren, filtern, sortieren und einschränken.

Mitarbeiter erstellen

Zuordnung validieren und Konto erstellen.

Mitarbeiter abrufen

Einen Mitarbeiter über seine undurchsichtige ID abrufen.

Mitarbeiter aktualisieren

Unterstützte Felder, Divisionszuordnung und Sperrstatus patchen.

​
Zentrale Regeln

  • Speichern Sie die JobHandy-Mitarbeiter-ID nach einem Match oder Create.
  • Verwenden Sie einen stabilen Kundenidentifikator wie employeeNumber, sofern Eindeutigkeit garantiert ist.
  • Verwenden Sie die E-Mail-Adresse nicht als einzigen langfristigen Key, wenn der Kunde deren Unveränderlichkeit nicht garantiert.
  • Lassen Sie Patch-Felder weg, die unverändert bleiben sollen.
  • Verwenden Sie null nur für nullable Felder, die geleert werden sollen.
  • Verwenden Sie eine Dry-Run-Vorschau-ID nicht in späteren Anfragen.

Leitfaden zur Mitarbeitersynchronisation

Implementieren Sie Identitätsabgleich, Checkpoints, Dry Runs, partielle Updates und Reconciliation nach Timeouts.
Zuletzt geändert am 20. Oktober 2026