Skip to content

Externe API-Integration

Diese Seite beschreibt die API-Endpunkte für externe Systeme (z. B. Integrationen oder Partnerdienste), die mit der gleichen API-Schlüssel-Authentifizierung arbeiten wie die Terminals.

Authentifizierung (API-Schlüssel-Flow)

  1. API-Schlüssel beschaffen

  2. Ein Administrator erstellt einen API-Schlüssel im System (Client-ID und Secret).

  3. Access-Token erhalten

  4. Endpoint: POST /api/auth/api
  5. Body: 
    {
  "id": "<clientId>",
  "secret": "<clientSecret>"
}

  6. Response: 

    {
  "access_token": "<jwt>",
  "refresh_token": "<refresh-token>",
  "expires_in": 3600
}

  7. API-Aufrufe autorisieren

  8. Header: Authorization: Bearer <access_token>

Refresh-Token nutzen

Access-Tokens laufen nach expires_in Sekunden ab. Verwenden Sie das Refresh-Token, um ein neues Access-Token zu erhalten:

  • Endpoint: POST /api/auth/refresh
  • Body: 
    {
  "refreshToken": "<refresh-token>"
}
  • Response: 
    {
  "access_token": "<jwt>",
  "expires_in": 3600
}

Hinweis: Alternativ kann das Refresh-Token (falls vorhanden) auch als Cookie übermittelt werden.

Arbeitszeit-Summen pro Nutzer abrufen

Der Endpoint liefert für einen Nutzer die Soll-, Pausen- und Arbeitsminuten sowie Abwesenheiten inklusive Abwesenheitsgrund für ein einzelnes Datum oder einen Datumsbereich.

  • Endpoint: GET /api/working-days/api/summary
  • Auth: Authorization: Bearer <access_token>
  • Query-Parameter:
  • email (Pflicht): E-Mail-Adresse des Zielnutzers
  • startDate (Pflicht): Startdatum im Format YYYY-MM-DD
  • endDate (Optional): Enddatum im Format YYYY-MM-DD (Standard: startDate)

Beispiel

GET /api/working-days/api/summary?email=user@example.com&startDate=2024-03-01&endDate=2024-03-31

Response

[
  {
    "date": "2024-03-01",
    "targetMinutes": 480,
    "pauseMinutes": 30,
    "workingMinutes": 450,
    "absenceValue": 480,
    "absenceReason": {
      "id": 3,
      "name": "Krankheit",
      "description": "Optionaler Beschreibungstext."
    }
  }
]