Quickstart

Dieser Quickstart prüft den vollständigen Integrationspfad, ohne dass ein dauerhafter Schreibvorgang erforderlich ist.

Voraussetzungen

Zugriff auf die JobHandy-Administration
Portalberechtigung IT, HR oder Company-Admin, um einen Key zu erstellen
Ein dedizierter API-Key mit dem erforderlichen Unternehmens- und Divisionsscope
Eine serverseitige Runtime, die Secrets sicher speichern kann

Zuerst API-Key erstellen

Erstellen und speichern Sie einen Key mit passendem Scope, bevor Sie die geschützten Beispiele ausführen.

1. Öffentliche Erreichbarkeit prüfen

curl --request GET \
  --url 'https://api.jobhandy.io/v1/health'

Eine erfolgreiche Antwort bestätigt, dass der öffentliche API-Endpoint erreichbar ist. Sie validiert weder den API-Key noch den Tenant-Scope oder den Zugriff auf geschützte Ressourcen.

2. Request-ID erzeugen

Verwenden Sie für jeden logischen Versuch eine neue UUID v4 oder v7. Die API gibt eine übermittelte ID zurück oder erzeugt selbst eine, wenn der Header fehlt.

X-Request-ID: {{requestId}}

X-Request-ID dient ausschließlich der Korrelation. Sie ist kein Idempotency Key.

3. Mitarbeiter auflisten

curl --request GET \
  --url 'https://api.jobhandy.io/v1/employees?page=1&pageSize=10' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Request-ID: {{requestId}}'

const requestId = crypto.randomUUID();
const response = await fetch(
  'https://api.jobhandy.io/v1/employees?page=1&pageSize=10',
  {
    headers: {
      'X-API-Key': process.env.JOBHANDY_API_KEY,
      'X-Request-ID': requestId,
    },
  },
);
const payload = await response.json();
console.log(response.status, response.headers.get('x-request-id'), payload);

import os
import uuid
import requests

request_id = str(uuid.uuid4())
response = requests.get(
    'https://api.jobhandy.io/v1/employees',
    params={'page': 1, 'pageSize': 10},
    headers={
        'X-API-Key': os.environ['JOBHANDY_API_KEY'],
        'X-Request-ID': request_id,
    },
    timeout=30,
)
print(response.status_code, response.headers.get('X-Request-ID'))
response.raise_for_status()
print(response.json())

$requestId = [guid]::NewGuid().ToString()
$headers = @{
    'X-API-Key'    = $env:JOBHANDY_API_KEY
    'X-Request-ID' = $requestId
}
Invoke-RestMethod `
    -Method Get `
    -Uri 'https://api.jobhandy.io/v1/employees?page=1&pageSize=10' `
    -Headers $headers

4. Bei Bedarf auf einen Tenant einschränken

Wenn der Key mehrere Unternehmen abdeckt, fügen Sie die Tenant-ID hinzu, die von JobHandy-Ressourcen zurückgegeben oder beim Integrations-Onboarding bereitgestellt wurde:

X-Tenant-ID: {{tenantId}}

Lassen Sie den Header weg, wenn bewusst eine Collection über alle Tenants im Scope benötigt wird. Siehe Tenant-Scope.

5. Filter-Quoting testen

curl --get 'https://api.jobhandy.io/v1/employees' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'filter=lastName="van Example"'

Der HTTP-Client URL-encodiert den unveränderten Filterausdruck. Werte mit Leerzeichen müssen in Anführungszeichen gesetzt werden.

6. Schreibvorgang ohne Speicherung validieren

Verwenden Sie eine unterstützte Schreiboperation mit dryRun=true. Das folgende Beispiel validiert eine Mitarbeiteränderung, speichert sie jedoch nicht:

curl --request PATCH \
  --url 'https://api.jobhandy.io/v1/employees/EMPLOYEE_ID?dryRun=true' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Request-ID: {{requestId}}' \
  --data '{"phoneNumber":"+49 221 1234567"}'

Ein erfolgreicher Dry Run gibt den voraussichtlichen Mitarbeiterzustand zurück. Er reserviert keinen Zustand; der reale Schreibvorgang kann weiterhin fehlschlagen, wenn sich die Ressource zwischen Validierung und Speicherung ändert.

7. Fehlerantwort erkennen

{
  "error": {
    "code": "TENANT_NOT_IN_SCOPE",
    "message": "The selected tenant is not available to this API key.",
    "requestId": "{{requestId}}"
  }
}

Verwenden Sie error.code für Programmlogik, error.message für die Diagnose und error.requestId für Logs und Supportanfragen.

Erfolgskriterien

Der Quickstart ist abgeschlossen, wenn alle folgenden Bedingungen erfüllt sind:

GET /health antwortet erfolgreich
eine geschützte Anfrage wird mit Ihrem API-Key authentifiziert
die Tenant-Auswahl verhält sich entsprechend dem Key-Scope
die Antwort enthält oder spiegelt X-Request-ID
ein gequoteter Filter liefert eine gültige Collection-Antwort
ein unterstützter Dry Run liefert eine Projektion, ohne Daten zu ändern
Ihre Logs enthalten weder den API-Key noch unnötige personenbezogene Daten

Produktiven Betrieb vorbereiten

Schließen Sie vor der Aktivierung eines Zeitplans die Sicherheits-, Retry-, Reconciliation-, Monitoring- und Betriebsmaßnahmen ab.

Erste Schritte

Architektur & Konzepte

Integrationsleitfäden

Betrieb

Voraussetzungen

Zuerst API-Key erstellen

1. Öffentliche Erreichbarkeit prüfen

2. Request-ID erzeugen

3. Mitarbeiter auflisten

4. Bei Bedarf auf einen Tenant einschränken

5. Filter-Quoting testen

6. Schreibvorgang ohne Speicherung validieren

7. Fehlerantwort erkennen

Erfolgskriterien

Produktiven Betrieb vorbereiten

​Voraussetzungen

Zuerst API-Key erstellen

​1. Öffentliche Erreichbarkeit prüfen

​2. Request-ID erzeugen

​3. Mitarbeiter auflisten

​4. Bei Bedarf auf einen Tenant einschränken

​5. Filter-Quoting testen

​6. Schreibvorgang ohne Speicherung validieren

​7. Fehlerantwort erkennen

​Erfolgskriterien

Produktiven Betrieb vorbereiten

Voraussetzungen

1. Öffentliche Erreichbarkeit prüfen

2. Request-ID erzeugen

3. Mitarbeiter auflisten

4. Bei Bedarf auf einen Tenant einschränken

5. Filter-Quoting testen

6. Schreibvorgang ohne Speicherung validieren

7. Fehlerantwort erkennen

Erfolgskriterien