# API-Referenz

Vollstaendige Referenz aller REST-API-Endpunkte. Basis-URL: `/api`. Authentifizierung via Sanctum Bearer-Token, sofern nicht als "public" markiert.

---

## Public (kein Auth)

### CAPTCHA

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/captcha` | CAPTCHA-Challenge generieren (SVG + Token). Rate-limited. |
| `GET` | `/captcha/settings` | CAPTCHA-Konfiguration (enabled, honeypot). |

```json
// GET /captcha
{ "enabled": true, "token": "abc...", "image_svg": "<svg>...</svg>", "accessible_text": "Was ergibt 3 plus 5?" }
```

### Formular-Submission

| Method | Path | Beschreibung |
|--------|------|--------------|
| `POST` | `/meldungen` | Neue Meldung einreichen. Rate-limited. |

Parameter: `template_slug` (required), dynamische Felder je Template, `captcha_token`, `captcha_answer`, `website_url` (Honeypot).

```json
// Response 201
{ "status": "success", "id": 42 }
```

### App-Einstellungen

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/app-name` | App-Name |
| `GET` | `/app-icon` | App-Icon (Lucide-Key oder Upload-URL) |
| `GET` | `/layout/settings` | Layout-Einstellungen (Header, Footer, Theme). Query: `locale` |
| `GET` | `/maintenance/status` | Wartungsmodus-Status. Query: `locale` |
| `GET` | `/demo/status` | Demo-Modus-Status und Reset-Timer |

### Geo

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/geo/bundeslaender` | Liste aller Bundeslaender |
| `GET` | `/geo/landkreise/{bundesland}` | Landkreise eines Bundeslandes |

### Template-Aufloesung

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/form-templates/{slug}` | Template mit eingebetteten Blocks fuer Rendering |

### Plan

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/plan` | Aktueller Plan-Typ, Features, Template-Limits |

### Health

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/health` | Health-Check (DB-Konnektivitaet) |

### Einladungen

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/invitations/{token}` | Einladungsdetails anzeigen |
| `POST` | `/invitations/{token}/accept` | Einladung annehmen |

### Webhooks

| Method | Path | Beschreibung |
|--------|------|--------------|
| `POST` | `/webhooks/stripe` | Stripe Billing Webhook (Signatur-validiert) |

---

## Auth (Login/Logout)

| Method | Path | Auth | Beschreibung |
|--------|------|------|--------------|
| `POST` | `/auth/login` | public | Login (email, password). Rate-limited. |
| `POST` | `/auth/two-factor-challenge` | public | 2FA-Verifizierung (two_factor_token, code oder recovery_code) |
| `POST` | `/auth/logout` | auth:sanctum | Logout (Token revoken) |
| `GET` | `/auth/me` | auth:sanctum | Aktueller Benutzer |
| `PUT` | `/auth/profile` | auth:sanctum | Profil aktualisieren (name, email, password) |

```json
// POST /auth/login → 2FA aktiv
{ "two_factor": true, "two_factor_token": "abc..." }

// POST /auth/login → direkt
{ "token": "1|abc...", "user": { "id": 1, "name": "...", "email": "...", "role": "admin" } }
```

### SSO

| Method | Path | Auth | Beschreibung |
|--------|------|------|--------------|
| `GET` | `/sso/providers` | public | Aktive SSO-Provider (Name + Typ) |
| `GET` | `/sso/{providerId}/redirect` | public | Redirect zu IdP (SAML/OIDC) |
| `GET/POST` | `/sso/{providerId}/callback` | public | IdP-Callback (SAML/OIDC) |
| `POST` | `/sso/{providerId}/login` | public | LDAP-Login (username, password). Rate-limited. |

---

## Authentifizierte Routen (auth:sanctum + demo)

### Zwei-Faktor-Authentifizierung

| Method | Path | Beschreibung |
|--------|------|--------------|
| `POST` | `/auth/two-factor/enable` | 2FA aktivieren (password). Gibt QR-Code-SVG + Recovery-Codes zurueck. |
| `POST` | `/auth/two-factor/confirm` | 2FA bestaetigen (code) |
| `DELETE` | `/auth/two-factor` | 2FA deaktivieren (password) |
| `POST` | `/auth/two-factor/recovery-codes` | Recovery-Codes neu generieren (password) |

### Meldungen

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/meldungen` | Paginierte Meldungsliste. Query: `template`, `per_page` |
| `GET` | `/meldungen/{id}` | Einzelne Meldung (Felder als Top-Level) |

### Dashboard

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/dashboard/templates` | Verfuegbare Templates fuer Dashboard |
| `GET` | `/dashboard/stats/{templateSlug}` | Statistiken fuer ein Template |

---

## Admin-Routen (auth:sanctum + admin)

### User-Verwaltung

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/users` | Alle Benutzer |
| `POST` | `/admin/users` | Benutzer anlegen (name, email, password, role) |
| `PUT` | `/admin/users/{user}` | Benutzer aktualisieren |
| `DELETE` | `/admin/users/{user}` | Benutzer loeschen |

### Settings

| Method | Path | Beschreibung |
|--------|------|--------------|
| `POST` | `/admin/app-name` | App-Name speichern (app_name) |
| `POST` | `/admin/app-icon` | App-Icon speichern (icon oder icon_file Upload) |
| `POST` | `/admin/maintenance` | Wartungsmodus (enabled, message, contact, info_text) |
| `POST` | `/admin/layout` | Layout-Einstellungen speichern (Header, Footer, Theme, Index) |
| `POST` | `/admin/layout/upload-logo` | Logo-Bild hochladen (logo: image) |

### CAPTCHA (Admin)

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/captcha` | Alle CAPTCHA-Settings (inkl. Schwierigkeit, Rate-Limit) |
| `POST` | `/admin/captcha` | CAPTCHA-Settings speichern (enabled, difficulty, forms_enabled, login_enabled, honeypot_enabled, rate_limit_per_hour) |

### Mail

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/mail` | Mail-Konfiguration |
| `POST` | `/admin/mail` | Mail-Konfiguration speichern (mailer, host, port, ...) |
| `POST` | `/admin/mail/test` | Test-E-Mail senden (to) |

### Testdaten

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/testdata/status` | Testdaten-Status pro Template |
| `POST` | `/admin/testdata/prompt` | KI-Prompt generieren (template_slug) |
| `POST` | `/admin/testdata/import` | Testdaten importieren (template_slug, records[]) |
| `POST` | `/admin/testdata/clear` | Testdaten loeschen (template_slug) |

### Meldungen verwalten

| Method | Path | Beschreibung |
|--------|------|--------------|
| `POST` | `/admin/meldungen/clear-by-template` | Meldungen eines Templates loeschen (template_slug) |

### API-Token-Verwaltung

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/tokens` | Alle API-Tokens |
| `POST` | `/admin/tokens` | Neuen Token erstellen (name, abilities[]) |
| `DELETE` | `/admin/tokens/{id}` | Token loeschen |

### BI-Feld-Metadaten

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/bi/felder` | Alle Templates mit ihren BI-Feldern (fuer Token-Hilfe) |

### Translations

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/translations` | Alle Uebersetzungen |
| `PUT` | `/admin/translations` | Uebersetzung speichern |
| `DELETE` | `/admin/translations/{id}` | Uebersetzung loeschen |
| `GET` | `/admin/translations/batch` | Batch-Abfrage |
| `GET` | `/admin/translations/export` | Export als JSON |
| `POST` | `/admin/translations/import` | Import aus JSON |

### Updates

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/updates/version` | Aktuelle Version |
| `GET` | `/admin/updates/check` | Auf Updates pruefen |
| `GET` | `/admin/updates/history` | Update-Historie |
| `POST` | `/admin/updates/perform` | Update durchfuehren |
| `POST` | `/admin/updates/rollback/{logId}` | Rollback |
| `POST` | `/admin/updates/token` | GitHub-Token speichern |
| `DELETE` | `/admin/updates/token` | GitHub-Token loeschen |

### Audit Logs (Plan: audit_log)

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/audit-logs` | Paginierte Audit-Logs |
| `GET` | `/admin/audit-logs/{id}` | Einzelner Audit-Log-Eintrag |

### Scheduled Reports (Plan: scheduled_reports)

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/reports` | Alle Berichte |
| `POST` | `/admin/reports` | Bericht erstellen (name, template_slug, frequency, recipient_emails[], ...) |
| `PUT` | `/admin/reports/{id}` | Bericht aktualisieren |
| `DELETE` | `/admin/reports/{id}` | Bericht loeschen |
| `POST` | `/admin/reports/{id}/test-send` | Test-Versand |
| `GET` | `/admin/reports/{id}/runs` | Ausfuehrungshistorie |

### Organization (Plan: multi_tenancy)

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/organization` | Aktuelle Organisation |
| `PUT` | `/admin/organization` | Organisation aktualisieren (name, slug, domain, settings) |
| `GET` | `/admin/organization/members` | Mitglieder |
| `POST` | `/admin/organization/invite` | Mitglied einladen (email, role) |
| `DELETE` | `/admin/organization/members/{userId}` | Mitglied entfernen |
| `GET` | `/admin/organization/invitations` | Offene Einladungen |
| `GET` | `/admin/organizations` | Alle Organisationen (Super-Admin) |

### SSO Provider (Plan: sso)

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/sso-providers` | Alle SSO-Provider |
| `POST` | `/admin/sso-providers` | Provider erstellen |
| `GET` | `/admin/sso-providers/{id}` | Provider-Details |
| `PUT` | `/admin/sso-providers/{id}` | Provider aktualisieren |
| `DELETE` | `/admin/sso-providers/{id}` | Provider loeschen |
| `POST` | `/admin/sso-providers/{id}/test` | Verbindung testen |

### Email Notifications (Plan: email_notifications)

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/email-notifications` | Alle Benachrichtigungen |
| `POST` | `/admin/email-notifications` | Benachrichtigung erstellen (template_id, event_type, recipients[], subject_template, body_template) |
| `PUT` | `/admin/email-notifications/{id}` | Aktualisieren |
| `DELETE` | `/admin/email-notifications/{id}` | Loeschen |
| `POST` | `/admin/email-notifications/{id}/test` | Test-Versand |

---

## Developer-Routen (auth:sanctum + developer)

### Form Blocks

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/form-blocks` | Alle Blocks |
| `POST` | `/admin/form-blocks` | Block erstellen |
| `GET` | `/admin/form-blocks/{id}` | Block-Details |
| `PUT` | `/admin/form-blocks/{id}` | Block aktualisieren |
| `DELETE` | `/admin/form-blocks/{id}` | Block loeschen |
| `PUT` | `/admin/form-blocks/reorder` | Blocks neu sortieren |

### Form Templates

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/admin/form-templates` | Alle Templates |
| `POST` | `/admin/form-templates` | Template erstellen |
| `GET` | `/admin/form-templates/{id}` | Template-Details |
| `PUT` | `/admin/form-templates/{id}` | Template aktualisieren |
| `DELETE` | `/admin/form-templates/{id}` | Template loeschen |
| `POST` | `/admin/form-templates/{id}/duplicate` | Template duplizieren |
| `GET` | `/admin/form-templates/{id}/export` | Template als JSON exportieren |
| `POST` | `/admin/form-templates/import` | Template aus JSON importieren |

---

## BI-API (auth:sanctum + ability:bi:read + Plan: bi_api)

Siehe [BI-API-Referenz](bi-api-referenz.md) fuer detaillierte Dokumentation.

| Method | Path | Beschreibung |
|--------|------|--------------|
| `GET` | `/bi/templates` | Verfuegbare Templates |
| `GET` | `/bi/{templateSlug}/felder` | Abfragbare Felder + Filter |
| `GET` | `/bi/{templateSlug}/daten` | Paginierte Rohdaten |
| `GET` | `/bi/{templateSlug}/stats/uebersicht` | Uebersichtsstatistiken |
| `GET` | `/bi/{templateSlug}/stats/zeitverlauf` | Zeitverlauf (monatlich) |
| `GET` | `/bi/{templateSlug}/stats/feld/{feldSlug}` | Feld-Statistik (GROUP BY) |