Skip to main content

​
Zugriff und API-Keys

Wie erstelle ich einen API-Key?

Öffnen Sie die JobHandy-Administration, wechseln Sie zu IT-Einstellungen, wählen Sie API-Keys und klicken Sie auf Create API Key. Siehe API-Key-Verwaltung.
Mindestens eine der Berechtigungen IT, HR oder Company-Admin ist erforderlich.
Ja. Verwenden Sie getrennte Keys für getrennte Integrationen, Verantwortlichkeiten oder Scopes.
Ein Key kann auf die Unternehmen und Divisionen begrenzt werden, die im Administrationsportal ausgewählt wurden. Die API stellt jedes autorisierte Unternehmen anschließend als Tenant-Kontext dar.
Der dokumentierte Betriebsprozess verlässt sich nicht auf Änderungen vorhandener Zugangsdaten. Erstellen Sie einen Ersatz-Key mit dem erforderlichen Namen und Scope, stellen Sie ihn bereit und prüfen Sie ihn, bevor Sie den alten Key deaktivieren.
Behandeln Sie die Anzeige bei der Erstellung als sicheren Erfassungszeitpunkt. Wenn die Zugangsdaten nicht mehr verfügbar sind, erstellen und verteilen Sie einen Ersatz, statt von einer Wiederherstellung des geheimen Werts auszugehen.
Eine Deaktivierung beendet die Authentifizierung und erlaubt eine spätere Reaktivierung. Eine Löschung nimmt den Key dauerhaft aus dem Portalprozess außer Betrieb.

​
Umgebungen und Tests

Gibt es eine öffentliche Sandbox- oder Stage-Basis-URL?

Der öffentliche Vertrag dokumentiert ausschließlich https://api.jobhandy.io/v1. Interne Entwicklungs-Hosts sind nicht Bestandteil der Kundenkonfiguration.
Nein. Der Modus validiert einen unterstützten Schreibvorgang gegen den aktuellen produktiven Scope und Zustand, ohne die dokumentierte Änderung oder Side Effects anzuwenden.
Nein. Ein Dry Run sperrt oder reserviert keinen Zustand. Behandeln Sie Konflikte beim realen Request erneut.

​
Tenant und Scope

Was ist der Unterschied zwischen Unternehmen und Tenant?

Unternehmen ist der fachlich sichtbare Portalbegriff. Tenant ist die technische API-Grenze und der Identifikator dieser Organisation.
Senden Sie den Header, wenn eine Operation sonst keinen eindeutigen Tenant bestimmen kann oder wenn eine Collection bewusst auf einen autorisierten Tenant eingeschränkt werden soll.
Nein. Der Header kann ausschließlich den bereits dem API-Key zugewiesenen Scope einschränken.
Verwenden Sie die Tenant-ID aus autorisierten Ressourcen-Responses oder die beim Integrations-Onboarding bereitgestellte ID. Verwenden Sie keinen Unternehmensnamen und keine Divisions-ID.
Nicht über PATCH /employees/{id}. Der Endpoint kann divisionId ausschließlich innerhalb desselben Tenants ändern oder entfernen.

​
Requests und Retries

Ist X-Request-ID erforderlich?

Der Header ist optional, wird aber dringend empfohlen. Fehlt er, erzeugt die API selbst eine ID.
Nein. Es handelt sich um Korrelationsmetadaten; die ID dedupliziert keine Anfrage.
Lesen oder suchen Sie die betroffene Ressource erneut, bevor Sie einen weiteren Schreibvorgang senden. Der Server kann die Änderung bereits gespeichert haben, bevor die Verbindung in einen Timeout gelaufen ist.
Nein. Request-Schemas sind geschlossen; unbekannte Eigenschaften werden abgelehnt.
Transiente Read-Fehler können in der Regel mit begrenztem Backoff sicher wiederholt werden. Berücksichtigen Sie bei 429 den Header Retry-After.

​
Collections und Filter

Wie groß darf eine Seite maximal sein?

pageSize akzeptiert Werte von 1 bis 1000; der Serverstandard ist 100.
Nein. Verwenden Sie genau ein vom Endpoint unterstütztes skalares Feld, optional mit vorangestelltem - für absteigende Sortierung.
String-Vergleiche sind case-insensitive. Enum-Werte bleiben case-sensitive.
Setzen Sie Werte mit Leerzeichen in Anführungszeichen und escapen Sie ein Apostroph mit \'. URL-encodieren Sie den vollständigen Filterwert.
Der öffentliche Vertrag garantiert keine Snapshot-Konsistenz. Verwenden Sie Checkpoints und berücksichtigen Sie parallele Änderungen.

​
Ressourcen

Kann ich einen Mitarbeiter löschen?

Es ist keine öffentliche Employee-Delete-Operation definiert. Verwenden Sie den dokumentierten Status blocked zum Sperren des Kontos und behandeln Sie die Löschung über den zuständigen Fachprozess.
Die geschäftliche E-Mail-Adresse ist über den öffentlichen Employee-Patch-Endpoint nicht änderbar.
Die Decision-Operation ist für Bestellungen im Status under_review vorgesehen. Eine finale Entscheidung kann ORDER_ALREADY_DECIDED zurückgeben; lesen und gleichen Sie den Zustand erneut ab, statt ihn zu überschreiben.
Nein. POST /incidents antwortet mit 422 EMPLOYEE_NOT_ACTIVATED und erstellt keinen Vorfall. Schließen Sie zuerst die Aktivierung des Mitarbeiters ab und senden Sie anschließend eine neue Anfrage mit einer neuen X-Request-ID.
Der Endpoint akzeptiert Bild- oder PDF-Anhänge für einen bearbeitbaren abgeschlossenen Vorfall, vorbehaltlich der Grenzwerte für Dateianzahl und vollständige Body-Größe.
Das Metadatenschema erlaubt ausdrücklich null, wenn keine Datei erzeugt wurde. Rufen Sie die Download-Operation nicht blind auf.

​
Betrieb

Wie hoch sind die numerischen Rate Limits?

Der Vertrag definiert die Header RateLimit-Policy, RateLimit und Retry-After anstelle eines einheitlichen festen Kontingents. Lesen Sie die wirksamen Werte aus den Responses.
Der aktuelle öffentliche v1-Vertrag definiert keine Endpoints zur Webhook-Registrierung oder Event-Subscription. Verwenden Sie clientinitiiertes Polling.
Die OpenAPI-Spezifikation ist der maßgebliche maschinenlesbare Vertrag. Erzeugen oder entwickeln Sie einen für Ihre Umgebung geeigneten Client und ergänzen Sie eigene Betriebskontrollen.
Senden Sie UTC-Zeit, Methode, Pfad, Status, Fehlercode, Request-ID, Tenant-Kontext und bereinigte Reproduktionsschritte. Senden Sie niemals den API-Key.
Zuletzt geändert am 2. September 2026