API-Referenz - Stampfactory

Überblick

Die Stampfactory API ist eine REST API und stellt alle Funktionen der Zeiterfassungs- und Personalverwaltungsplattform bereit. Sie ist mandantenfähig: jeder Mandant hat eine eigene Datenbank, und jede Anfrage wird über die Subdomain dem richtigen Mandanten zugeordnet.

Basis-URL

Jeder Mandant erreicht die API über seine eigene Subdomain. Der Pfad-Präfix ist immer /rest.

https://{tenant}.stamp.eu/rest

Für den Beispielmandanten demo lautet die Basis-URL also https://demo.stamp.eu/rest. Eigene Domains werden unterstützt; auch dort bleibt der Präfix /rest unverändert.

Authentifizierung

Die API nutzt Bearer-Token (Laravel Sanctum). Den Token liefert der Login-Endpunkt. Er muss bei allen weiteren Anfragen im Header Authorization mitgeschickt werden.

Token beziehen

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

Token verwenden

curl -H "Authorization: Bearer {token}" \
  https://demo.stamp.eu/rest/employees

Mit DELETE /rest/login wird der Token wieder ungültig, GET /rest/login liefert die angemeldete Person, und PUT /rest/login ändert das eigene Passwort.

Der Terminal-Endpunkt POST /rest/terminal/{code} ist bewusst ohne Token erreichbar, damit Hardware-Terminals ohne Anmeldung stempeln können.

Datenformate

Die folgenden Formate gelten verbindlich für die gesamte API.

Typ	Format	Beispiel
Dauer (Anzeige)	String `HH:MM:SS.mmm`, Feldname ohne Suffix	`"08:00:00.000"`
Dauer (Rohwert)	Ganzzahl in Millisekunden, Feldname mit Suffix `_ms`	`28800000`
Datum	ISO 8601 (`YYYY-MM-DD`)	`"2026-07-25"`
Fachliche Zeitstempel (Stempelungen, Korrekturen)	ISO 8601 in der Zeitzone des Mandanten	`"2026-07-25T08:00:00+02:00"`
Technische Metadaten (`created_at`, `updated_at`)	ISO 8601 in UTC	`"2026-07-25T06:00:00+00:00"`
IDs	UUID beziehungsweise TypeID als String	`"9d3f8c1a-4b2e-4f7d-9a11-2c5e8b0d1f34"`
Arbeitszeit-Flags	Ganzzahlige Bitmaske im Feld `flags`	`512` steht für Feiertag
Monats-Perioden	`YYYY-MM`	`"2026-07"`

Dauerwerte gibt es je nach Feld in zwei Varianten. Für Anzeigen eignet sich der formatierte String, für Berechnungen der Millisekundenwert mit dem Suffix _ms. Beide beschreiben denselben Wert.

Arbeitszeit-Flags

Das Feld flags fasst die Eigenschaften eines Arbeitstags als Bitmaske zusammen. Ein Tag kann mehrere Eigenschaften gleichzeitig tragen, etwa halber Urlaubstag und Feiertag. Die Prüfung erfolgt per bitweisem UND:

const VACATION = 1 << 2; // 4
const isVacation = (day.flags & VACATION) !== 0;

Antwortformat

Erfolgreiche Antworten liefern die fachliche Nutzlast unter data. Ausgenommen sind die Stempel-Endpunkte POST /rest/terminal/{code} und /rest/mobile, die aus Kompatibilitätsgründen ein flaches Objekt zurückgeben. Listen sind, sofern sie paginiert werden, im Laravel-Paginator-Format aufgebaut und enthalten neben data zusätzlich links und meta.

{
  "data": [ ],
  "links": { "first": "…", "last": "…", "prev": null, "next": "…" },
  "meta": { "current_page": 1, "per_page": 25, "total": 137 }
}

Fehlerformat

Alle Fehler mit Status 4xx und 5xx nutzen denselben Envelope. Das Feld type verweist auf die passende Stelle in der Fehlerreferenz.

{
  "request_id": "9f1c2f7e-5b3c-4a11-9a1d-2f0a5c7d3e88",
  "timestamp": "2026-07-25T06:00:00Z",
  "message": "Das Feld Code ist erforderlich.",
  "field_errors": {
    "code": ["Das Feld Code ist erforderlich."]
  },
  "errors": [
    {
      "title": "Validation Error",
      "detail": "The given data was invalid.",
      "type": "https://docs.stampfactory.eu/errors#validation_error",
      "_meta": {
        "path": "/rest/employees",
        "fields": { "code": ["Das Feld Code ist erforderlich."] }
      }
    }
  ]
}

field_errors erscheint nur bei Validierungsfehlern (Status 422). Endpunktspezifische Zusatzdaten wie warnings, earliest oder code stehen kanonisch in errors[0]._meta; gleichlautende Felder auf oberster Ebene sind eine Übergangslösung für ältere Clients. Die request_id entspricht dem Response-Header X-Request-Id und hilft dem Support dabei, eine konkrete Anfrage wiederzufinden.

Fehlerreferenz

Alle Fehlercodes mit Bedeutung, typischen Auslösern und Beispielantworten.

Berechtigungsmodell

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

Systemrollen

Rolle	Beschreibung
Workspace Admin	Vollzugriff auf alle Ressourcen. Kann nicht gelöscht oder eingeschränkt werden.
HR Admin	Verwaltung von Mitarbeitenden, Abwesenheiten und Berichten.
Lohnbuchhaltung	Zugriff auf Lohndaten, Zeiterfassungs-Export und Berichte.
Zeiterfassung Admin	Verwaltung von Arbeitszeiten, Arbeitszeitmodellen und Feiertagskalendern.
Mitarbeitende	Eigene Stempelungen (Web, Mobil, Terminal) und eigene Benachrichtigungen.

Zusätzlich lassen sich über POST /rest/roles eigene Rollen mit individuellen Berechtigungen anlegen.

Berechtigungen

Berechtigungen sind in Funktionsbereiche gegliedert:

Bereich	Berechtigungen
Mitarbeitende	`employees:view`, `employees:manage`, `employees:assign_roles`
Zeiterfassung	`time-tracking:view`, `time-tracking:correct`, `time-tracking:export`, `time-tracking:clock-web`, `time-tracking:clock-mobile`, `time-tracking:clock-terminal`
Abwesenheiten	`absences:view`, `absences:manage`, `absences:approve`
Arbeitszeitmodelle	`schedule-models:view`, `schedule-models:manage`
Feiertagskalender	`holidays:view`, `holidays:manage`
Organisation	`org:manage`
Projekte	`projects:view`, `projects:manage`
Lohnabrechnung	`payroll:view`, `payroll:manage`
Berichte	`reports:view`
Einstellungen	`settings:manage`
Benachrichtigungen	`notifications:own`, `notifications:department`

Sichtbarkeit

Die Sichtbarkeit von Mitarbeitenden richtet sich nach der zugewiesenen Rolle:

Workspace Admin: sieht alle Mitarbeitenden.
Rollen mit employees:view oder employees:manage: sehen Mitarbeitende der eigenen Organisationseinheit und aller untergeordneten Einheiten.
Rollen ohne diese Berechtigungen: sehen nur die eigenen Daten.

Module

Funktionen lassen sich pro Mandant als Modul aktivieren. Ist ein Modul deaktiviert, antworten die zugehörigen Endpunkte mit Status 403 und dem Code forbidden. Welche Module ein Mandant nutzt, liefert GET /rest/ in den Feldern modules und available_modules.

Modul	Beschreibung
`leave_requests`	Abwesenheitsverwaltung
`overtime_accounts`	Überstundenkonten
`projects`	Projektzeiterfassung
`locations`	Standortverwaltung
`departments`	Abteilungsstruktur
`cost_centers`	Kostenstellenverwaltung
`short_work`	Kurzarbeit
`shift_roster`	Dienstplan
`payroll`	Lohnabrechnung und Monatsabschluss
`datev_payroll`	DATEV Lohn und Gehalt
`export`	Zeitwirtschafts-Export
`nfc_clock`	Stempeln per NFC-Tag
`geo_clock`	Standortprüfung beim Stempeln
`mobile_app`	Mobile App
`terminals`	Hardware-Terminals
`employee_documents`	Digitale Personalakte
`eau`	Elektronische Arbeitsunfähigkeitsbescheinigung
`dls_import`	Import aus Lohnprogrammen
`webhooks`	Webhooks
`mood`	Stimmungsbarometer
`custom_domain`	Eigene Domain

Die Prüfungen nach Arbeitszeitgesetz sind kein Modul. Sie laufen für jeden Mandanten automatisch mit und lassen sich nicht abschalten.

Anmelden

​Überblick

​Basis-URL

​Authentifizierung

​Token beziehen

​Token verwenden

​Datenformate

​Arbeitszeit-Flags

​Antwortformat

​Fehlerformat

Fehlerreferenz

​Berechtigungsmodell

​Systemrollen

​Berechtigungen

​Sichtbarkeit

​Module

Überblick

Basis-URL

Authentifizierung

Token beziehen

Token verwenden

Datenformate

Arbeitszeit-Flags

Antwortformat

Fehlerformat

Berechtigungsmodell

Systemrollen

Berechtigungen

Sichtbarkeit

Module