API Übersicht

Die job.rocks Partner API ist eine integrationsbezogene Schnittstelle für flexible Staffing-Prozesse. Sie ermöglicht den Austausch von Personalbedarf, Schichten, Bearbeitungs- und Besetzungsstatus sowie freigegebenen Arbeitszeiten. Optional können abrechnungsrelevante Zeitkategorien für Payroll-/ERP-Systeme bereitgestellt werden.

Hinweis: Der verfügbare Funktionsumfang wird pro Partnerintegration festgelegt und freigeschaltet. Sandbox- und Produktionszugänge werden individuell bereitgestellt.

Basis-URL

Endpunkte und URLs werden bei Freischaltung bereitgestellt:

Sandbox:    https://sandbox-api.job.rocks/partner/v1
Produktion: https://api.job.rocks/partner/v1

Die oben genannten URLs beschreiben den geplanten Integrationsumfang. Die technische Freischaltung erfolgt pro Partnerprojekt.

OpenAPI-Spezifikation und Sandbox-Zugang werden im Rahmen des Partner-Onboardings bereitgestellt. Die Freischaltung erfolgt nach Abstimmung des Integrationsumfangs und der benötigten Datenfelder. Auf Wunsch stellen wir zusätzlich eine Postman Collection oder Beispiel-Requests für die freigeschalteten Endpunkte bereit.

Authentifizierung

Die API verwendet partner-spezifische Zugangsdaten, um kurzlebige Bearer Tokens auszustellen.

Im Rahmen des Onboardings stellt job.rocks dem Partner Sandbox- und später Produktions-Zugangsdaten bereit. Der Partner authentifiziert sich über den Authentifizierungs-Endpunkt und erhält ein Access Token für die jeweilige Umgebung.

POST /auth/token
Content-Type: application/json

Beispiel-Request:

{
  "partner_id": "YOUR_PARTNER_ID",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Beispiel-Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Alle nachfolgenden API-Requests verwenden das zurückgegebene Bearer Token:

Authorization: Bearer YOUR_ACCESS_TOKEN

Für reguläre API-Requests ist kein zusätzlicher Partner-Identifier-Header erforderlich. Das Bearer Token identifiziert den Partner, die Umgebung und den erlaubten Scope.

Eigenschaften

• Per-Partner Credentials: Jeder Partner erhält eigene Authentifizierungs-Zugangsdaten
• Token-basierter Zugriff: Reguläre API-Requests benötigen nur das Bearer Token
• Tenant-Scoped: Tokens sind auf die vereinbarte Partnerintegration und Instanz beschränkt
• Sandbox & Produktion: Getrennte Zugangsdaten und Tokens für Test und Live
• IP-Allowlisting: Optional für Produktion verfügbar

Datenformate

• Request Body: application/json
• Response Body: application/json
• Datumsformate: ISO 8601 (YYYY-MM-DD für Daten, HH:mm für Zeiten)
• Zeitzonen: Europe/Zurich (CET/CEST), sofern nicht anders vereinbart

Kernkonzepte

Die Partner API stellt ausschliesslich die für die Integration relevanten Bedarfs-, Status- und Ergebnisdaten bereit.

Integrationsrichtungen

Status-Modell

Staffing Orders durchlaufen folgende Status:

Status werden von job.rocks gesetzt und können von Partnern gelesen werden.

Idempotenz

• external_order_id ist der Idempotenz-Schlüssel für Staffing Orders und muss pro Partner eindeutig sein
• external_shift_id muss pro Order eindeutig sein
• Erneutes POST mit gleicher externer ID gibt die bestehende Ressource zurück
• Bei abweichendem Payload mit gleicher externer ID wird 409 CONFLICT zurückgegeben

Paginierung

Alle Listen-Endpunkte unterstützen Cursor-basierte Paginierung:

GET /staffing-orders?limit=50&cursor=***==

Response:

{
  "items": [...],
  "next_cursor": "***=="
}

Versionierung

• Breaking Changes nur in neuer Major-Version (/v2)
• Additive Felder (neue optionale Felder) jederzeit möglich
• Partner sollen unbekannte Felder ignorieren
• Deprecation Window: mindestens 90 Tage vor Entfernung

Datenschutz

Personenbezogene Daten werden nur im jeweils vereinbarten Umfang bereitgestellt. Standardmässig arbeitet die API mit pseudonymen Referenzen und aggregierten Statusdaten.

Fehlermodell

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "required_headcount must be at least 1",
    "request_id": "req_123"
  }
}

Fehlercodes sind stabil; Fehlermeldungen sind nicht für programmgesteuerte Logik gedacht.

Jede Response enthält einen X-Request-Id Header für Support-Anfragen.

Rate Limits

Rate Limits werden pro Partnerintegration konfiguriert. Jede Response enthält entsprechende Header:

X-Request-Id: req_123
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1782316800
Retry-After: 60

Header können je nach Umgebung und Integrationsscope abweichen.

Verfügbare Bereiche

Support

Bei technischen Fragen kontaktieren Sie uns unter support@job.rocks.