FleetFlow — API-Referenz

Alle schreibenden Aktionen der Anwendung laufen über Next.js-API-Routen unter /api. Jede Route verwendet den serverseitigen, Cookie-authentifizierten Supabase-Client; vor jeder schreibenden Aktion wird die Berechtigung der Rolle geprüft (Berechtigungsmatrix, siehe Projektdokumentation, Abschnitt 3.5). Zusätzlich greifen die Row-Level-Security-Policies der Datenbank als zweite Kontrollebene.

Konventionen

Alle Routen (außer POST /api/register) erfordern eine angemeldete Session mit bestandener 2FA (durchgesetzt in der Middleware).
Fehlende Berechtigung → 403 mit JSON-Fehlermeldung; Validierungsfehler → 400; nicht gefunden → 404.
Request-/Response-Body: JSON (Ausnahme: PDF-Endpunkte liefern application/pdf).
Listen-Endpunkte mit Pagination liefern { data, count } (Seitengröße 50).

Authentifizierung & Registrierung

Methode & Pfad	Zweck
`POST /api/register`	Einmalige Firmen-Registrierung (Einzelmandant): legt `companies`-Zeile und Admin-Konto in einem Schritt an. Gesperrt (409), sobald eine Firma existiert. Login/2FA selbst laufen direkt über Supabase Auth (kein eigener Endpunkt).

Fahrzeuge

Methode & Pfad	Zweck
`GET /api/vehicles`	Fahrzeugliste (Filter: Status, Typ, Freitextsuche; paginiert)
`POST /api/vehicles`	Fahrzeug anlegen
`GET /api/vehicles/[id]`	Fahrzeugdetail
`PATCH /api/vehicles/[id]`	Fahrzeug ändern (auch: `letzte_aufbereitung` zurücksetzen)
`DELETE /api/vehicles/[id]`	Fahrzeug löschen (Löschrecht erforderlich)
`POST /api/vehicles/[id]/damage-reports`	Eigenständige Schadensmeldung (Fotos + Beschreibung, KI-Analyse)
`POST /api/vehicles/[id]/insurance-policies`	Versicherungspolice anlegen (inkl. PDF-Storage-Pfad)
`POST /api/vehicles/[id]/versicherungsfaelle`	Versicherungs-Schadensfall anlegen

Kunden

Methode & Pfad	Zweck
`GET /api/customers`	Kundenliste (Freitextsuche; paginiert)
`POST /api/customers`	Kunde anlegen (privat/firma)
`GET /api/customers/[id]`	Kundendetail
`PATCH /api/customers/[id]`	Kunde ändern
`DELETE /api/customers/[id]`	Kunde löschen (Löschrecht erforderlich)

Buchungen

Methode & Pfad	Zweck
`GET /api/bookings`	Buchungsliste (`?status=&page=`, liefert `{ data, count }`)
`POST /api/bookings`	Buchung anlegen (inkl. Verfügbarkeits- und Preisprüfung)
`GET /api/bookings/[id]`	Buchungsdetail
`PATCH /api/bookings/[id]`	Buchung ändern / Statusübergang (nur gültige Übergänge; setzt ggf. Fahrzeugstatus)
`DELETE /api/bookings/[id]`	Buchung löschen (Löschrecht erforderlich)
`GET /api/bookings/availability`	Verfügbarkeitsprüfung Fahrzeug × Zeitraum
`GET /api/bookings/[id]/documents/[kind]/pdf`	Angebot bzw. Auftragsbestätigung als PDF (`kind`: `angebot` \| `auftragsbestaetigung`; wird bei jedem Abruf frisch gerendert)
`POST /api/bookings/[id]/documents/[kind]/send`	Dokument per E-Mail versenden (Resend bzw. Simulation, Antwort enthält `email_simuliert`)

Übergaben

Methode & Pfad	Zweck
`POST /api/handovers`	Ausgabe-/Rückgabeprotokoll anlegen (km, Tank, Zustand, Gegenstände, Fotos)

Rechnungen

Methode & Pfad	Zweck
`GET /api/invoices`	Rechnungsliste
`POST /api/invoices`	Rechnung aus abgeschlossener Buchung erzeugen (fortlaufende Nummer, Netto/MwSt./Brutto)
`GET /api/invoices/[id]`	Rechnungsdetail
`PATCH /api/invoices/[id]`	Statusübergang (Entwurf → Versendet → Bezahlt / Storniert)
`GET /api/invoices/[id]/pdf`	Rechnungs-PDF (im Storage gecacht)
`POST /api/invoices/[id]/send`	Rechnung per E-Mail versenden

Versicherungen

Methode & Pfad	Zweck
`DELETE /api/insurance-policies/[id]`	Police löschen (Löschrecht `insurance` erforderlich)
`PATCH /api/versicherungsfaelle/[id]`	Schadensfall ändern / Statusübergang (offen → in Bearbeitung → abgeschlossen)
`DELETE /api/versicherungsfaelle/[id]`	Schadensfall löschen

Werkstatt

Methode & Pfad	Zweck
`GET /api/werkstattauftraege`	Auftragsliste (Werkstatt sieht nur eigene Aufträge)
`POST /api/werkstattauftraege`	Fahrzeug an Werkstatt übergeben (Trigger setzt Fahrzeugstatus → „in Wartung")
`PATCH /api/werkstattauftraege/[id]`	Auftrag annehmen / Notiz / abschließen (Abschluss setzt Fahrzeugstatus → „verfügbar")

KI

Methode & Pfad	Zweck
`POST /api/ai/extract`	Buchungsdaten aus E-Mail-Text extrahieren (Gemini, Fallback: Regex-Heuristik)
`POST /api/ai/damage`	Schadensanalyse eines hochgeladenen Fotos (Gemini Vision, Fallback: Mock; löst Storage-URL aus `storage_path` auf)

Preisberechnung

Methode & Pfad	Zweck
`POST /api/pricing/quote`	Preisaufschlüsselung für Fahrzeug × Zeitraum (alle Faktoren einzeln + Gesamtpreis)

Einstellungen & Firma

Methode & Pfad	Zweck
`GET /api/settings`	Globale Einstellungen lesen (Aufbereitungsintervall, Preisfaktoren)
`PATCH /api/settings`	Einstellungen ändern (Schreibrecht `settings` erforderlich, Validierung)
`GET /api/company`	Firmendaten lesen
`PATCH /api/company`	Firmendaten ändern (Schreibrecht `companies` erforderlich)

Benutzer, Rollen & Berechtigungen

Methode & Pfad	Zweck
`GET /api/team`	Alle Benutzerkonten mit Rolle
`POST /api/team`	Mitarbeiterkonto anlegen (Admin-API, E-Mail + Initialpasswort)
`PATCH /api/team/[id]`	Rolle eines Kontos ändern
`GET /api/roles`	Rollen inkl. Berechtigungsmatrix
`POST /api/roles`	Neue Rolle anlegen
`PATCH /api/roles/[id]`	Rolle umbenennen (Systemrollen geschützt)
`DELETE /api/roles/[id]`	Rolle löschen (Systemrollen geschützt)
`PUT /api/roles/[id]/permissions`	Berechtigungsmatrix der Rolle setzen (11 Ressourcen × Sehen/Bearbeiten/Löschen)