API-Dokumentation

Die meisten API-Endpunkte erfordern eine gültige Supabase-Session (Cookie-basiert nach Login). Öffentliche Endpunkte wie Portal-Links und Rechnungslinks verwenden signierte Tokens.

// Alle /api/intern/* Routen erfordern eingeloggte Session
// Öffentliche Routen (kein Login):
GET /api/health
GET /mitarbeiter-portal/[token]
GET /rechnung/[token]
GET /portal/[token]

Empfängt eingehende Daten von externen Systemen (z.B. Zeiterfassung, DATEV-Export-Trigger). Endpunkt: POST /api/intern/webhook

Request

POST /api/intern/webhook
Content-Type: application/json
X-Webhook-Secret: <dein-secret>

{
  "event": "zeiterfassung.export",
  "mandant_id": "uuid-...",
  "daten": {
    "monat": "2026-06",
    "mitarbeiter": [
      { "id": "uuid-...", "stunden": 160, "ueberstunden": 12 }
    ]
  }
}

Response

{
  "status": "received",
  "processed": 1,
  "timestamp": "2026-06-01T10:00:00.000Z"
}

Events

Öffentlicher Link für Mitarbeiter zum Abruf ihrer Lohnzettel. Kein Login erforderlich — Zugang via signiertem Token.

GET /mitarbeiter-portal/{token}

// Token wird automatisch generiert und per E-Mail versendet
// Gültigkeitsdauer: 90 Tage (konfigurierbar)

Response (HTML-Seite)

// Rendert HTML-Seite mit:
// - Liste aller Lohnzettel des Mitarbeiters
// - Download als PDF pro Monat
// - Persönliche Daten (Name, Beschäftigungsart)

Öffentlicher Link für Kunden zur Einsicht und Bezahlung einer Rechnung.

GET /rechnung/{token}

// Zeigt Rechnung mit:
// - Rechnungsdetails (Positionen, Beträge)
// - PDF-Download
// - Bezahlinformation (SEPA / Überweisung)

Token-Generierung (intern)

// Intern: Token wird bei Rechnungserstellung automatisch generiert
// Format: /api/intern/rechnungen/{id}/token (POST)
// Response:
{
  "token": "eyJ...",
  "link": "https://lohnheld.de/rechnung/eyJ...",
  "expires_at": "2026-09-01T00:00:00.000Z"
}

Vollständiges Selbstbedienungs-Portal für Lohnheld-Kunden mit Rechnungsübersicht, Mandanten und Verträgen.

GET /portal/{token}

// Zeigt:
// - Alle Rechnungen des Kunden
// - Aktive Mandate
// - Vertragsdetails
// - Kontaktmöglichkeit

Öffentlicher Status-Endpunkt für Monitoring und Uptime-Checks.

GET /api/health

Response

{
  "status": "ok",
  "db": "ok",
  "db_latency_ms": 12,
  "timestamp": "2026-06-01T10:00:00.000Z",
  "version": "19.0.0",
  "response_ms": 15
}

Status-Werte