API-Referenz

Ü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.

Datenformate

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

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://stamp-factory.eu/docs/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.

Berechtigungsmodell

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

Systemrollen

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

Berechtigungen

Berechtigungen sind in Funktionsbereiche gegliedert:

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.