API-Referenz

API-Referenz

Übersicht der Veasytor REST API. Alle Endpunkte erfordern Authentifizierung via Supabase Session (Cookie-basiert), sofern nicht anders angegeben.

Authentifizierung

Veasytor verwendet Supabase Auth (Client-seitig). Zusaetzlich stehen server-seitige API-Routen fuer Login und Magic-Link zur Verfuegung (ADR-PS-262).

Methode	Beschreibung
E-Mail + Passwort	supabase.auth.signInWithPassword() (Client) oder POST /api/auth/login (Server)
Magic Link	supabase.auth.signInWithOtp() (Client) oder POST /api/auth/magic-link (Server)
Google OAuth	supabase.auth.signInWithOAuth()

Auth API-Routen:

Endpunkt	Methode	Beschreibung
/api/auth/login	POST	Server-seitiger Login mit E-Mail + Passwort (ADR-PS-262)
/api/auth/magic-link	POST	Magic-Link per E-Mail senden (ADR-PS-262)
/api/auth/check-email	GET	E-Mail-Existenz prüfen
/api/auth/verify-email	GET	E-Mail-Verifizierung
/api/auth/redeem-code	POST	Einladungscode einlösen
/api/auth/resend-verification	POST	Verifizierungs-E-Mail erneut senden
/api/auth/reset-password	POST	Passwort zurücksetzen
/api/auth/sessions	GET	Aktive Sessions abfragen
/api/auth/session	ANY	Catch-All: JSON 404 mit Verweis auf /api/auth/sessions (Plural). Verhindert HTML-404 fuer fehlerhafte Aufrufe (ADR-PS-268).
/api/auth/redirect	GET	Auth-Redirect-Handler
/api/auth/track-login	POST	Login-Tracking: Erstellt USER_LOGIN AuditLog-Einträge pro aktiver Tenant-Membership mit Subdomain-Kontext (portal/go/admin). System-Admins ohne Memberships erhalten keinen Eintrag.

Parkplätze

Endpunkt	Methode	Beschreibung
/api/parking-spaces	GET	Parkplätze der aktiven Liegenschaft
/api/parking-spaces/[id]	GET/PUT/DELETE	Einzelner Parkplatz
/api/parking-spaces/reserve	POST	Parkplatz reservieren
/api/parking-reservations	GET	Aktive Reservierungen

Buchungen

Endpunkt	Methode	Beschreibung
/api/admin/bookings	GET	Buchungen auflisten (Portal)
/api/bookings/[id]/cancel	POST	Buchung stornieren
/api/bookings/[id]/extend	POST	Buchung verlängern
/api/bookings/[id]/end-early	POST	Buchung vorzeitig beenden

Benutzer & Bewohner

Endpunkt	Methode	Beschreibung
/api/admin/users	GET	Benutzer auflisten (System-Admin)
/api/user/create	POST	Benutzer erstellen
/api/user/role	GET/PUT	Benutzerrolle abfragen/ändern
/api/user/settings	GET/PUT	Benutzereinstellungen
/api/user/preferences	GET/POST	Sprach- & Benachrichtigungspräferenzen (nur in /app/-Routen)
/api/user/profile-status	GET	Profilstatus
/api/user/memberships	GET	Liegenschafts-Mitgliedschaften
/api/user/subdomain-access	GET	Subdomain-Zugriffsrechte
/api/user/notifications	GET	Benachrichtigungen
/api/user/notifications/read	POST	Als gelesen markieren
/api/user/push-token	POST	Push-Token registrieren
/api/user/data-export	POST	DSGVO-Datenexport
/api/user/delete-request	POST	DSGVO-Löschanfrage

Mandant – Support-Zugang (ADR-PS-306, ersetzt ADR-PS-294)

Endpunkt	Methode	Beschreibung
/api/tenant/support-access	GET	Aktive SupportAccessRequests + 30-Tage-History für den aktuellen Mandanten. Portal: OWNER/MANAGER.
/api/tenant/support-access/[requestId]/revoke	POST	SupportAccessRequest widerrufen. Cascade: DATA_VIEW-Widerruf entzieht auch TENANT_ACCESS. Audit-Log SUPPORT_ACCESS_REVOKED.

DSGVO-Maskierung: Ohne aktiven Support-Zugang werden personenbezogene Daten (E-Mail, Name) in allen Admin-API-Responses maskiert. In der globalen Benutzerliste (/api/admin/users ohne tenantId-Filter) sind PII immer maskiert.

Einladungen & Mitglieder

Endpunkt	Methode	Beschreibung
/api/tenant/members/invite	POST	Neuen Benutzer einladen (Team oder Property)
/api/tenant/members/resend	POST	Einladung erneut senden
/api/tenant/members/[id]	PUT/DELETE	Mitglied/Einladung verwalten. PUT Body: roles, optional propertyId/apartmentId fuer Property-Rollen. PropertyMember wird automatisch erstellt/entfernt (ADR-PS-273)
/api/tenant/invitations/accept	POST	Auto-Join nach E-Mail-Verifikation. Erstellt TenantMember + PropertyMember. Idempotent/race-safe via upsert (ADR-PS-273, ADR-PS-274)
/api/invite/accept	POST	Einladung annehmen mit Passwort-Setup. Erstellt TenantMember + PropertyMember (ADR-PS-273)
/api/tenant/invite	POST	Tenant-Einladung
/api/residents/send-invitation	POST	Einladung an bestehenden Bewohner senden (ADR-PS-237)
/api/residents/active-invitations	GET	Aktive Einladungen abrufen
/api/residents/revoke-invitation	POST	Einladung widerrufen
/api/residents/leave-property	POST	Liegenschaft verlassen. Loescht TenantMember (nur RESIDENT-Rolle) + PropertyMember + VisitorPropertyAccess. Body: \{ propertyId \}

Wohnungen

Endpunkt	Methode	Beschreibung
/api/apartments	GET/POST	Wohnungen auflisten/erstellen
/api/apartments/[id]	GET/PUT/DELETE	Einzelne Wohnung
/api/apartments/[id]/details	GET	Wohnungsdetails
/api/apartments/[id]/users	GET	Bewohner einer Wohnung
/api/apartments/generate-token	POST	Einladungstoken generieren

Liegenschaften

Endpunkt	Methode	Beschreibung
/api/properties	GET	Liegenschaften des Nutzers
/api/properties/[id]	GET/PUT	Einzelne Liegenschaft
/api/admin/properties	GET	Alle Liegenschaften (System-Admin)
/api/admin/properties/[id]	GET/PUT/DELETE	Liegenschaft verwalten (System-Admin)

Abrechnung & Abonnement

Endpunkt	Methode	Beschreibung
/api/tenant/subscription	GET	Abo-Informationen (Plan, Status, Limits, Testphase)
/api/billing/invoices	GET	Stripe-Rechnungen (Status: PAID/PENDING/OVERDUE/CANCELLED)
/api/billing/portal	POST	Stripe Customer Portal Session erstellen
/api/webhooks/stripe	POST	Stripe Webhook Handler

Hinweis: GET /api/billing existiert nicht. Abo-Informationen werden über /api/tenant/subscription abgerufen, Rechnungen über /api/billing/invoices.

Dashboard & Statistiken

Endpunkt	Methode	Beschreibung
/api/dashboard/stats	GET	Dashboard-Statistiken (Auslastung etc.)
/api/dashboard/chart	GET	Dashboard Chart-Daten
/api/dashboard/overstays	GET	Überschreitungen
/api/tenant/stats	GET	Mandanten-Statistiken (Management-Übersicht)
/api/statistics/bookings	GET	Buchungs-Statistiken (Datumsbereich, Liegenschaft)
/api/statistics/bookings-chart	GET	Buchungs-Zeitreihe (Tag/Woche/Monat)
/api/statistics/incidents	GET	Vorfälle-Statistiken inkl. hourlyDistribution, selfResolutionRate, participationRate, avgResponsesPerInquiry, timezone-Parameter (Default: Europe/Zurich)
/api/statistics/incidents-chart	GET	Vorfälle-Zeitreihe
/api/statistics/audit-actions	GET	Audit-Log Aktionen (aggregiert)
/api/statistics/top-lists	GET	Top-Listen (nur type=bookings oder type=incidents). Incidents: mostActiveRespondents, mostAffectedApartments, fastestResolutions, recurringPlates, mostReporters, mostIncidentSpaces
/api/statistics/parking-usage	GET	Parkplatz-Auslastung
/api/statistics/property-visitors	GET	Besucher pro Liegenschaft
/api/statistics/user-visitors	GET	Besucher pro Nutzer (Go App)
/api/statistics/resident-activity	GET	Bewohner-Aktivität
/api/statistics/visitor-count	GET	Besucherzählung
/api/statistics/reservation-duration	GET	Reservierungsdauer
/api/statistics/platform-stats	GET	Plattform-Statistiken (öffentlich)
/api/admin/stats	GET	System-Admin Statistiken

Hinweis: GET /api/statistics existiert nicht. Statistiken werden über spezifische Endpunkte abgerufen (z.B. /api/statistics/bookings, /api/dashboard/stats).

Anfragen & Nachrichten

Endpunkt	Methode	Beschreibung
/api/inquiries	GET/POST	Parkplatz-Anfragen
/api/inquiries/[id]	GET/PUT	Einzelne Anfrage
/api/inquiries/[id]/claim	POST	DSGVO-konforme Besucher-Verifizierung (“Blind Claim”). Rate-limited (5 Versuche/10 Min)
/api/inquiries/[id]/warn	POST	Abschleppwarnung für gemeldetes Fahrzeug senden
/api/inquiries/respond	POST	Auf Anfrage antworten (Ja/Nein/Veto)
/api/messages	GET/POST	Nachrichten
/api/messages/[id]	GET	Einzelne Nachricht
/api/notifications	GET	System-Benachrichtigungen

Support

Endpunkt	Methode	Beschreibung
/api/support/list	GET	Support-Tickets auflisten
/api/support/create	POST	Neues Ticket erstellen (authentifiziert)
/api/support/create-public	POST	Ticket ohne Authentifizierung erstellen (Rate-limited: 5/Stunde). Für öffentliche Support-Seite
/api/support/[id]	GET/PUT	Einzelnes Ticket. PII-Maskierung basierend auf SupportAccessRequest-Status (ADR-PS-306)
/api/support/[id]/access/request	POST	Support-Zugriffsanfrage erstellen (DATA_VIEW oder TENANT_ACCESS). Auto-Split bei TENANT_ACCESS (ADR-PS-306)
/api/support/[id]/access/[requestId]/grant	POST	Zugriffsanfrage gewähren. Zwei-Tier-Auth: Orphaned User oder Tenant OWNER/MANAGER (ADR-PS-306)
/api/support/[id]/access/[requestId]/deny	POST	Zugriffsanfrage ablehnen. CASCADE: DATA_VIEW-Deny entzieht auch TENANT_ACCESS (ADR-PS-306)
/api/support/[id]/claim	POST	Ticket beanspruchen (SUPPORT/ADMIN). Setzt Status auf ASSIGNED (ADR-PS-306)
/api/support/[id]/reassign	POST	Ticket neu zuweisen (ADMIN). Widerruft alle Zugänge des bisherigen Bearbeiters (ADR-PS-306)
/api/support/[id]/reply	POST	Antwort auf Ticket. Optional: newStatus (z.B. RESOLVED, CLOSED) für Manager – setzt den Ticket-Status direkt in der DB. Auto-Revoke des Datenzugangs bei RESOLVED/CLOSED
/api/support/[id]/messages	GET	Ticket-Nachrichten abrufen

System-Admin

Endpunkt	Methode	Beschreibung
/api/admin/tenants	GET	Mandanten auflisten (inkl. isActive, deactivatedAt, deactivationGracePeriodDays)
/api/admin/tenants	POST	Mandant erstellen
/api/admin/tenants	PATCH	Mandant aktualisieren. Actions: DEACTIVATE (setzt isActive=false, revoked alle Member-Sessions), REACTIVATE (setzt isActive=true), CREDIT_DAYS (Tage-Gutschrift, kumulative Berechnung, 730-Tage-Cap). Body: \{ tenantId, action, data? \}
/api/admin/tenants/[id]/stats	GET	Aggregierte Tenant-Statistiken (Buchungen, Vorfälle, Scans, Logins, Nutzung, Aktivitäts-Chart). Query-Params: period (7d/30d/90d/365d), propertyId (optional). SuperAdmin-only.
/api/admin/tenants/[id]/credits	GET	Gutschrift-Historie für einen Mandanten
/api/admin/tenants	DELETE	Mandant endgültig löschen. Kaskadierende Löschung aller zugehörigen Daten (inkl. TenantCredit, 17+ Tabellen) in einer Transaktion. Body: \{ id \}
/api/admin/system-alerts	GET/POST	System-Warnungen
/api/admin/system-alerts/[id]	PUT/DELETE	Warnung bearbeiten
/api/admin/rules	GET/PATCH	Regelwerk (GET: ?propertyId=…, PATCH: Body mit propertyId + Regeln)
/api/properties/settings/[id]	GET/PUT	Vollständige Liegenschafts-Einstellungen (inkl. Regeln, Reservierungen, Abschleppen)
/api/admin/settings	GET/PUT	System-Einstellungen
/api/admin/releases	GET/POST	Release Notes
/api/admin/feedbacks	GET	Feedback-Übersicht
/api/admin/subscription-plans	GET/POST	Abo-Pläne

Bulk-Operationen

Endpunkt	Methode	Beschreibung
/api/bulk/validate	POST	Bulk-Import validieren
/api/bulk/execute	POST	Bulk-Import ausführen
/api/bulk/template	GET	Import-Template
/api/bulk/generate-pdf	POST	PDF generieren

Fehler-Antworten

Alle Endpunkte verwenden konsistente Fehler-Formate:

{
  "error": "Beschreibung des Fehlers",
  "code": "ERROR_CODE"
}

HTTP Status	Bedeutung
200	Erfolg
207	Multi-Status – Aktion teilweise erfolgreich (z.B. Einladung erstellt, aber E-Mail konnte nicht gesendet werden). Frontend zeigt Warning-Toast.
307	Redirect (z.B. unauthentifizierter Zugriff auf geschuetzte Routen → Login)
400	Ungültige Anfrage
401	Nicht authentifiziert
403	Keine Berechtigung
404	Nicht gefunden
500	Server-Fehler

Auth-First Routing (307 Redirect)

Geschuetzte Subdomains (Portal, Admin, Go) verwenden ein Auth-First Pattern: Unauthentifizierte Requests auf beliebige Pfade erhalten einen HTTP 307 Redirect zur Login-Seite – nicht 404. Dies ist ein Sicherheitsprinzip, das verhindert, dass Applikationsstruktur an unauthentifizierte Nutzer preisgegeben wird.

• www.veasytor.app: Oeffentlich, kein Auth-Check (ADR-PS-257: ProtectedRoute Bypass). 404 fuer nicht-existierende Seiten.
• portal.veasytor.app: 307 → Login (unauthentifiziert), 404 via Next.js (authentifiziert).
• admin.veasytor.app: 307 → Login (unauthentifiziert), 404 via Next.js (authentifiziert).
• go.veasytor.app: 307 → Login (unauthentifiziert), 404 via Next.js (authentifiziert).

SEO & OpenGraph

Alle Marketing-Seiten (www) verwenden NextSeo fuer OpenGraph und Twitter Meta-Tags:

• Default-Konfiguration in next-seo.config.ts (og:type, og:locale, og:siteName, og:image /icons/icon-512.png 512x512, Twitter summary_large_image). Fallback-Rewrites fuer /images/og-image.jpg und /images/og-image.png in next.config.mjs (ADR-PS-265/269).
• Per-Page Overrides mit <NextSeo openGraph=\{\{...\}\} /> fuer Titel, Beschreibung und Canonical-URL.
• Language-Alternates (DE, EN, FR, IT) fuer internationale SEO.
• SSR-Rendering: OG- und Twitter-Meta-Tags werden server-seitig im initialen HTML gerendert, sodass Crawler (Google, Facebook, Twitter, LinkedIn) und Tools wie curl korrekte Vorschauen erhalten (ADR-PS-254).

SEO-Landingpages (ADR-PS-260, ADR-PS-270)

4 themenspezifische SEO-Landingpages fuer den CH-Markt:

URL	Hauptkeyword	Slug
/parkraummanagement-wohnanlagen	Parkraummanagement Wohnanlagen	parkraummanagement
/besucherparkplaetze-verwalten	Besucherparkplaetze verwalten	besucherparkplaetze
/falschparker-loesen	Falschparker loesen	falschparker
/parkplatz-software-schweiz	Parkplatz-Software Schweiz	parkplatzSoftware

Jede Seite hat: Hero, Problem (mit Bullet-Points), Solution, Benefits Grid (6 Cards), USP-Highlight (Bewohner-Crowdsourcing), Social Proof, FAQ (5 Fragen, JSON-LD FAQPage Schema), CTA, Related Topics. Alle Texte in DE/EN/FR/IT via src/locales/*/seoLanding.ts. Wiederverwendbares Layout: src/components/marketing/landing/SeoLandingPage.tsx.

SSR-Architektur (ADR-PS-270): Content wird server-seitig via getSeoLandingData() in getServerSideProps aufgeloest und als typisierte Props an die Komponenten uebergeben. Dadurch enthaelt der initiale HTML-Response den vollstaendigen Content (800+ Woerter), korrekte JSON-LD Schemas (SoftwareApplication + FAQPage) und Meta-Tags mit echten Texten – wichtig fuer Crawler (Google, Facebook, etc.). Die Komponenten nutzen kein useTranslation() fuer SEO-Inhalte.

Cross-Subdomain Session (SSO)

Alle Subdomains teilen eine gemeinsame Supabase-Session via Cookie mit domain=.veasytor.app:

• Browser-Client (component.ts): Setzt/entfernt Cookies mit domain=.veasytor.app in Production.
• Server-Middleware (middleware.ts): Setzt Cookies ebenfalls mit domain=.veasytor.app in Production (ADR-PS-252).
• Sprache: veasytor_lang-Cookie mit domain=.veasytor.app (ADR-PS-167).
• Logout: supabase.auth.signOut() loescht das geteilte Session-Cookie → Logout propagiert automatisch zu allen Subdomains.