Stempel-Vorgänge

Dieses Modul beschreibt die API-Endpunkte zur Verwaltung von Stempel-Vorgängen (engl. punch events). Ein Stempel-Vorgang repräsentiert einen Zeitpunkt mit einem Typ (Start, Stop, Pausenbeginn, Pausenende). Die Endpunkte erlauben das Erstellen, Anzeigen, Auflisten und Löschen (Soft-Delete) von Vorgängen. Stempel-Vorgänge werden verwendet, um Arbeitszeiten (Zeiterfassungen) zu erfassen.

Gültige Attribute

Attribut	Beschreibung	Details
`discarded_at`	Zeitpunkt der Entfernung (oder `null`)	Kann nicht manuell gesetzt werden. Wird beim Löschen automatisch gesetzt (Soft-Delete).
`punched_at`	Zeitpunkt des Stempelns	Kann nicht manuell gesetzt werden. Wird serverseitig beim Erstellen gesetzt.
`punch_type`	Art des Vorgänges	Muss gesetzt werden. Zulässige Werte: `'start'`, `'stop'`, `'break_start'`, `'break_stop'`.
`user_id`	ID des Benutzers, dem das Vorgang zugeordnet ist	Kann nicht manuell gesetzt werden. Wird im Backend auf den aktuellen Benutzer gesetzt.

Beziehungen

Folgende Beziehungen können mit dem Parameter include in den Request eingebunden werden:

Beziehung	Typ	Beschreibung
`user`	has_one	Der Benutzer, dem das Stempel-Vorgang zugeordnet ist.

Meta-Daten: Berechtigungen

Können über den meta[permissions]-Parameter in den Request eingebunden werden. Sie geben an, welche Aktionen der aktuelle Benutzer auf einem Stempel-Vorgang ausführen kann.

Gruppe	Beschreibung
`actions`	Gibt an, ob der Benutzer den Stempel-Vorgang löschen (`delete`) kann.

Erstellen

Mit diesem Endpunkt kannst du ein neues Stempel-Vorgang erstellen.

Endpunkt

POST /api/v1/punch_events

Request

{
  "data": {
    "type": "punch_event",
    "attributes": {
      "punch_type": "start"
    }
  }
}

Response

{
  "data": {
    "id": "0e2f7b86-9b1e-4c1a-9d9a-7a0b6f1c5e3d",
    "type": "punch_event",
    "attributes": {
      "punch_type": "start",
      "punched_at": "2025-08-12T08:15:30Z",
      "user_id": "c2c3a4c9-5a9e-4ad8-9b7b-9a7d6c5b2e1f",
      "discarded_at": null
    }
  }
}

Anzeigen

Mit diesem Endpunkt kannst du die Details eines einzelnen Stempel-Vorgänges abrufen.

Endpunkt

GET /api/v1/punch_events/:id

Parameter

Name	Beschreibung
`id`	Die ID des Stempel-Vorgänges, das abgerufen wird.

Response

{
  "data": {
    "id": "0e2f7b86-9b1e-4c1a-9d9a-7a0b6f1c5e3d",
    "type": "punch_event",
    "attributes": {
      "punch_type": "start",
      "punched_at": "2025-08-12T08:15:30Z",
      "user_id": "c2c3a4c9-5a9e-4ad8-9b7b-9a7d6c5b2e1f",
      "discarded_at": null
    }
  }
}

Auflisten

Mit diesem Endpunkt kannst du alle Stempel-Vorgänge abrufen, für die du die Berechtigung hast.

Endpunkt

GET /api/v1/punch_events

Response

{
  "data": [
    {
      "id": "0e2f7b86-9b1e-4c1a-9d9a-7a0b6f1c5e3d",
      "type": "punch_event",
      "attributes": {
        "punch_type": "start",
        "punched_at": "2025-08-12T08:15:30Z",
        "user_id": "c2c3a4c9-5a9e-4ad8-9b7b-9a7d6c5b2e1f",
        "discarded_at": null
      }
    }
  ]
}

Beispiele

Alle Stempel-Vorgänge auflisten:

GET /api/v1/punch_events

Nach Typ filtern:

GET /api/v1/punch_events?filter[punch_type]=eq:start

Nach Benutzer filtern:

GET /api/v1/punch_events?filter[user_id]=eq:123

Sortieren nach Stempel-Zeit (absteigend):

GET /api/v1/punch_events?sort=-punched_at

Löschen

Mit diesem Endpunkt kannst du ein Stempel-Vorgang löschen. Das Vorgang wird soft-deleted; discarded_at wird automatisch gesetzt.

Endpunkt

DELETE /api/v1/punch_events/:id

Parameter

Name	Beschreibung
`id`	Die ID des Stempel-Vorgänges, das gelöscht wird.

Response

{
  "data": {
    "id": "0e2f7b86-9b1e-4c1a-9d9a-7a0b6f1c5e3d",
    "type": "punch_event",
    "attributes": {
      "punch_type": "start",
      "punched_at": "2025-08-12T08:15:30Z",
      "user_id": "c2c3a4c9-5a9e-4ad8-9b7b-9a7d6c5b2e1f",
      "discarded_at": "2025-08-12T10:03:11Z"
    }
  }
}