Skip to main content

​
Überblick

Die Stampfactory API ist eine REST API, die alle Funktionen der Zeiterfassungs- und Personalverwaltungsplattform bereitstellt. Alle Endpunkte sind mandantenfähig und erfordern eine gültige Subdomain. Base URL: https://{tenant}.stamp.eu/rest

​
Authentifizierung

Die API verwendet Bearer-Token-Authentifizierung (Laravel Sanctum). Tokens werden über den Login-Endpunkt bezogen und müssen bei allen authentifizierten Anfragen als Authorization-Header mitgesendet werden: 
curl -H "Authorization: Bearer {token}" \
  https://demo.stamp.eu/rest/employees

​
Token beziehen

curl -X POST https://demo.stamp.eu/rest/login \
  -H "Content-Type: application/json" \
  -d '{"code": "admin", "password": "1234"}'

​
Zeitformate

FormatBeschreibungBeispiel
ZeitstempelISO 8601, UTC2024-01-15T08:00:00.000000Z
DatumISO 86012024-01-15
DauerHH:MM:SS.mmm08:00:00.000
MonatYYYY-MM2024-01

​
Berechtigungsmodell

Die API verwendet rollenbasierte Zugriffskontrolle (RBAC). Jede Benutzerin bzw. jeder Benutzer erhält genau eine Rolle, die bestimmt, auf welche Funktionen Zugriff besteht.

​
Systemrollen

RolleBeschreibung
Workspace AdminVollzugriff auf alle Ressourcen. Kann nicht gelöscht oder eingeschränkt werden.
HR AdminVerwaltung von Mitarbeitenden, Abwesenheiten und Berichten.
LohnbuchhaltungZugriff auf Lohndaten, Zeiterfassungs-Export und Berichte.
Zeiterfassung AdminVerwaltung von Arbeitszeiten, Schichtmodellen und Feiertagskalendern.
MitarbeitendeEigene Stempelungen (Web, Mobil, Terminal) und eigene Benachrichtigungen.
Zusätzlich können über POST /roles benutzerdefinierte Rollen mit individuellen Berechtigungen erstellt werden.

​
Berechtigungen

Berechtigungen sind in Funktionsbereiche gegliedert:
BereichBerechtigungen
Mitarbeitendeemployees:view, employees:manage, employees:assign_roles
Zeiterfassungtime-tracking:view, time-tracking:correct, time-tracking:export, time-tracking:clock-web, time-tracking:clock-mobile, time-tracking:clock-terminal
Abwesenheitenabsences:view, absences:manage, absences:approve
Schichtmodelleschedule-models:view, schedule-models:manage
Feiertagskalenderholidays:view, holidays:manage
Organisationorg:manage
Projekteprojects:view, projects:manage
Lohnabrechnungpayroll:view, payroll:manage
Berichtereports:view
Einstellungensettings:manage
Benachrichtigungennotifications:own, notifications:department

​
Sichtbarkeit

Die Sichtbarkeit von Mitarbeitenden richtet sich nach der zugewiesenen Rolle:
  • Workspace Admin: Sieht alle Mitarbeitenden.
  • Rollen mit employees:view/employees:manage: Sehen Mitarbeitende der eigenen Organisationseinheit und aller untergeordneten Einheiten.
  • Rollen ohne diese Berechtigungen: Sehen nur die eigenen Daten.

​
Module

Die API unterstützt modulare Funktionen, die pro Mandant aktiviert oder deaktiviert werden können. Wenn ein Modul deaktiviert ist, geben die zugehörigen Endpunkte 403 Forbidden zurück.
ModulBeschreibung
leave_requestsAbwesenheitsverwaltung
projectsProjektzeiterfassung
departmentsAbteilungsstruktur
cost_centersKostenstellenverwaltung
short_workKurzarbeit
datev_payrollDATEV Lohn & Gehalt
datev_exportDATEV-Export
nfc_tagsNFC-Tag-Verwaltung
reportsHR-Berichte
payrollLohnabrechnung

​
Fehlerbehandlung

Die API gibt standardisierte Fehlermeldungen zurück: 
// 422 Validierungsfehler
{
  "message": "The given data was invalid.",
  "errors": {
    "code": ["The code field is required."],
    "name": ["The name field is required."]
  }
}

// 401 Nicht authentifiziert
{
  "message": "Unauthenticated."
}

// 403 Keine Berechtigung
{
  "message": "Forbidden."
}

// 404 Nicht gefunden
{
  "message": "Not found."
}