Architektur und Ressourcenmodell - JobHandy Developers

Die JobHandy Public API ist eine synchrone REST-Schnittstelle. Kundensysteme initiieren jede öffentliche Anfrage; der aktuelle öffentliche v1-Vertrag definiert keine Webhook-Endpoints oder Event-Subscriptions.

Systemgrenze

Verantwortungsaufteilung

Verantwortung	Kundenintegration	JobHandy API
API-Key sicher speichern	Ja	Nein
Polling und Synchronisation planen	Ja	Nein
Quellfelder auf API-Felder abbilden	Ja	Nein
`X-Request-ID` erzeugen und protokollieren	Empfohlen	Gibt sie zurück oder erzeugt sie
API-Key-Scope erzwingen	Nein	Ja
Request-Schema und fachlichen Zustand validieren	Nein	Ja
Mehrdeutige Ergebnisse von Schreibvorgängen abgleichen	Ja	Stellt den aktuellen Ressourcenstatus bereit
Heruntergeladene Dateien nach dem Abruf schützen	Ja	Schützt API-Zugriff und Download-Scope

Ressourceneigentum

Ressource	Eigentumsgrenze	Öffentliche Schreibmöglichkeiten
Tenant	API-Key-Scope	Keine Operation zum Erstellen, Aktualisieren oder Löschen von Tenants
Division	Genau ein Tenant	Erstellen und aktualisieren
Mitarbeiter	Kein oder ein Tenant; Division optional	Erstellen und unterstützte Felder aktualisieren
Bestellung	Genau ein Tenant und ein Mitarbeiter	Lesen und einmalige HR-Entscheidung aus dem dokumentierten Status erfassen
Vorfall	Mitarbeiter im autorisierten Scope	Erstellen, unterstützte Felder aktualisieren, zulässige Anhänge hochladen
Payroll-Exportdokument	Genau ein Tenant	Metadaten lesen und verfügbare Datei herunterladen

Side Effects von Schreiboperationen

Operation	Persistente Wirkung	Zusätzlicher Side Effect	Verhalten im Dry Run
Mitarbeiter erstellen	Erstellt ein Konto	Sendet eine E-Mail zur Passwortvergabe	Kein Konto und keine E-Mail
Mitarbeiter aktualisieren	Ändert unterstützte Felder	Im Vertrag ist kein zusätzlicher Side Effect angegeben	Keine Speicherung
Bestellung entscheiden	Speichert die endgültige HR-Entscheidung	Sendet die zugehörigen Benachrichtigungen	Keine Entscheidung und keine Benachrichtigungen
Vorfall erstellen	Erstellt den Vorfall	Setzt Melder- und Lifecycle-Metadaten	Keine Speicherung
Vorfall aktualisieren	Ändert unterstützte Vorfallsfelder	Serverseitige Lifecycle-Regeln können angewendet werden	Keine Speicherung
Vorfallsanhänge hochladen	Speichert zulässige Dateien	Im Vertrag ist kein zusätzlicher Side Effect angegeben	Validiert ohne Speicherung
Division erstellen	Erstellt einen Hierarchieknoten	Im Vertrag ist kein zusätzlicher Side Effect angegeben	Keine Speicherung
Division aktualisieren	Ändert Hierarchie, Name, Reihenfolge oder Kostenstelle	Im Vertrag ist kein zusätzlicher Side Effect angegeben	Keine Speicherung

Der OpenAPI-Vertrag ist maßgeblich. Gehen Sie nicht von zusätzlichen E-Mails, Benachrichtigungen oder Folgeaktionen aus, die nicht dokumentiert sind.

Beziehungen zwischen Identifikatoren

Ressourcen-IDs sind undurchsichtige Anwendungsidentifikatoren. Leiten Sie aus Zeichenfolge oder Reihenfolge keine fachliche Bedeutung ab.

Tenant-ID
  -> wird für X-Tenant-ID und Tenant-Felder verwendet
Divisions-ID
  -> wird für parentId und employee.divisionId verwendet
Mitarbeiter-ID
  -> wird von Bestellungen und Vorfällen referenziert
Bestellanhang-ID
  -> wird ausschließlich beim Download-Endpoint für Bestellanhänge verwendet
Payroll-Exportdokument-ID
  -> wird für Metadatenabruf und Download verwendet

Integrationsmodell

Der öffentliche Vertrag definiert Request- und Response-Verhalten. Kundenspezifische fachliche Verantwortlichkeiten, Zeitpläne, Feldmappings und nachgelagerte Aufbewahrung bleiben Bestandteil des Integrationsdesigns.

Zuletzt geändert am 27. August 2026