Mitarbeiter synchronisieren

Eine zuverlässige Synchronisation trennt Identitätsabgleich, Tenant-Zuordnung, Validierung, Mutation und Checkpointing. Erstellen Sie nicht bei jedem Importlauf einen neuen JobHandy-Mitarbeiter.

Source-of-Truth-Modell

Legen Sie vor der Implementierung für jedes gemappte Feld die fachliche Verantwortung fest.

Feldgruppe	Empfohlener Verantwortlicher	Verhalten der Integration
Geschäftliche E-Mail-Adresse	HR-/Kundenprozess bei der Erstellung; über diesen Endpoint nicht patchbar	Änderung als getrennten fachlichen Prozess behandeln
Personalnummer	Kunden-HR-System, sofern stabil	Als Matching-Key verwenden, wenn Eindeutigkeit garantiert ist
Kontakt- und Adressdaten	Abgestimmtes Quellsystem	Nur geänderte unterstützte Felder patchen
`blocked`	Abgestimmter Offboarding-/Kontoprozess	Explizit setzen; nicht als Löschung behandeln
Tenant	Zuordnungsprozess	Beim Create auflösen; Public Patch verschiebt bereits zugeordnete Mitarbeiter nicht
Division	HR-Organisationsquelle	Innerhalb desselben Tenants patchen oder mit `null` entfernen
JobHandy-`id`	JobHandy	Nach Match oder Create speichern und für spätere Requests verwenden

Reihenfolge des Matchings

Gespeicherte JobHandy-Mitarbeiter-ID
Stabile employeeNumber, wenn das Quellsystem Eindeutigkeit garantiert
Ein anderes ausdrücklich vereinbartes eindeutiges Mapping
E-Mail-Adresse nur, wenn der Kunde deren Unveränderlichkeit und Eindeutigkeit garantiert

Wenn eine Abfrage null oder mehr als einen plausiblen Treffer liefert, stoppen Sie die automatische Erstellung und leiten Sie den Datensatz zur Reconciliation weiter.

Swimlane der Synchronisation

Zuordnung auflösen

Senden Sie X-Tenant-ID, wenn der Key mehrere mögliche Tenants enthält.
Senden Sie divisionId, wenn der ausgewählte Tenant keine eindeutige zulässige Division ergibt.
Verwenden Sie ausschließlich eine Division innerhalb des Ziel-Tenants und API-Key-Scopes.
divisionId: null entfernt die Divisionszuordnung, verschiebt den Mitarbeiter aber nicht in einen anderen Tenant.

Mitarbeiter finden

curl --get 'https://api.jobhandy.io/v1/employees' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-ID: {{tenantId}}' \
  --data-urlencode 'filter=employeeNumber=EMP-1042'

Speichern Sie nach einem erfolgreichen Match die zurückgegebene JobHandy-id.

Sicher erstellen

Bestehenden Treffer ausschließen

Suchen Sie anhand der gespeicherten JobHandy-ID oder stabilen Personalnummer.

Zuordnung und Payload validieren

Rufen Sie POST /employees?dryRun=true mit den finalen Headern und dem finalen Body auf.

Create ausführen

Senden Sie dieselbe Anfrage ohne dryRun=true.

Reale ID speichern

Speichern Sie ausschließlich die ID aus der 201-Response ohne Dry Run.

Side Effect dokumentieren

Ein erfolgreiches Create sendet eine E-Mail zur Passwortvergabe. Erstellen Sie keine doppelten Konten, um diese E-Mail erneut auszulösen.

Nur geänderte Felder patchen

{
  "phoneNumber": "+49 221 1234567",
  "divisionId": "68920e08eeaea4f2301eecb3"
}

Nullable Patch-Eigenschaften können mit null geleert werden. Lassen Sie Eigenschaften weg, die unverändert bleiben sollen.

{
  "phoneNumber": null,
  "divisionId": null
}

Checkpoint-Modell

Speichern Sie mindestens:

sourceEmployeeId
jobHandyEmployeeId
sourceVersion or watermark
lastSuccessfulAtUtc
lastRequestId
lastResult

Reconciliation nach Timeout

Häufige Fehler

Fehler	Bedeutung	Maßnahme
`DUPLICATE_RESOURCE`	Eine Eindeutigkeitsregel wird bereits durch einen anderen Datensatz erfüllt	Vorhandenen Mitarbeiter finden und abgleichen
`EMPLOYEE_PLACEMENT_AMBIGUOUS`	Divisionsbeschränkter Scope ergibt kein eindeutiges Ziel	Zulässige `divisionId` senden
`TENANT_CONTEXT_AMBIGUOUS`	Mehr als ein Tenant ist möglich	`X-Tenant-ID` senden
`INVALID_REFERENCE`	Referenzierter Tenant oder referenzierte Division ist nicht verfügbar	Scope und Referenzen aktualisieren
`409` oder `422` nach Dry Run	Zustand hat sich geändert oder finale Validierung weicht ab	Erneut lesen und validieren; keinen blinden Retry durchführen

Erste Schritte

Architektur & Konzepte

Integrationsleitfäden

Betrieb

Source-of-Truth-Modell

Reihenfolge des Matchings

Swimlane der Synchronisation

Zuordnung auflösen

Mitarbeiter finden

Sicher erstellen

Nur geänderte Felder patchen

Checkpoint-Modell

Reconciliation nach Timeout

Häufige Fehler

​Source-of-Truth-Modell

​Reihenfolge des Matchings

​Swimlane der Synchronisation

​Zuordnung auflösen

​Mitarbeiter finden

​Sicher erstellen

​Nur geänderte Felder patchen

​Checkpoint-Modell

​Reconciliation nach Timeout

​Häufige Fehler

Source-of-Truth-Modell

Reihenfolge des Matchings

Swimlane der Synchronisation

Zuordnung auflösen

Mitarbeiter finden

Sicher erstellen

Nur geänderte Felder patchen

Checkpoint-Modell

Reconciliation nach Timeout

Häufige Fehler