fotospiel-app/docs/prp/tenant-app-specs/api-usage.md

API-Nutzung der Tenant Admin App

Diese Dokumentation beschreibt alle API-Endpunkte der Tenant Admin App. Alle Requests sind tenant-scoped und erfordern ein Sanctum Personal Access Token (PAT) mit der Fähigkeit tenant-admin bzw. tenant:<id>.

Authentifizierung

Passwort-Login (PAT)

• Endpoint: POST /api/v1/tenant-auth/login
• Body (application/json): { "login": "username oder email", "password": "••••" }
• Response: { token, token_type, abilities[], user { ... } }
• Fehler: 422 bei ungültigen Daten, 429 bei Rate-Limit (throttle:tenant-auth).
• Hinweis: login akzeptiert E-Mail oder Usernamen. Erfolgreiche Logins revoken vorhandene PATs mit Name tenant-admin.

Session→PAT Exchange (Google/Login-Shell)

• Endpoint: POST /api/v1/tenant-auth/exchange
• Middleware: Sanctum stateful cookies (SANCTUM_STATEFUL_DOMAINS), throttle:tenant-auth.
• Use-Case: Nach Google-Login oder Marketing-Checkout Session wird das PAT ohne erneute Passwort-Eingabe ausgegeben.
• Response: identisch zum Passwort-Login.

Token Status & Logout

• GET /api/v1/tenant-auth/me – liefert { user, tenant, abilities } und spiegelt die PAT-Fähigkeiten wider.
• POST /api/v1/tenant-auth/logout – löscht das aktuelle PAT aus personal_access_tokens.

Legacy Payload /tenant/me

• Endpoint: GET /api/v1/tenant/me
• Response: historisches Format (tenant_id, remaining_events, scopes), betrieben über denselben PAT.
• Kompatibilität: Dient älteren Clients als Übergang; neue Features sollten /tenant-auth/me verwenden.

Dashboard

Stats laden

• GET /api/v1/tenant/dashboard
  • Headers: Authorization: Bearer {token}
  • Response: { active_package, active_events, new_photos, task_progress }
  • Zweck: Übersicht-Daten für Dashboard-Cards (active_package: current tenant package info)

Events

Events-Liste

• GET /api/v1/tenant/events
  • Headers: Authorization: Bearer {token}
  • Params:
    • page=1 (Pagination)
    • per_page=50 (max für Mobile)
    • status=draft|active|archived (Filter)
    • search=query (Suche in Titel/Ort)
  • Response: { data: Event[], current_page, last_page, total }
  • Event-Shape: { id, title, date, location, status, photoCount, slug }

Event erstellen

• POST /api/v1/tenant/events
  • Headers: Authorization: Bearer {token}, Content-Type: application/json
  • Body: { title, date, location, description, package_id }
  • Response: 201 Created mit erstelltem Event
  • Validierung: Prüft Tenant-Package (Reseller-Limit) und erstellt Event-Package (Einmalkauf oder Free)

Event-Details

• GET /api/v1/tenant/events/{slug}
  • Headers: Authorization: Bearer {token}
  • Response: Erweitertes Event mit { tasks[], members, stats { likes, views, uploads } }

Event updaten

• PATCH /api/v1/tenant/events/{slug}
  • Headers: Authorization: Bearer {token}, Content-Type: application/json, If-Match: {etag}
  • Body: Partial Event-Daten (title, date, location, description)
  • Response: Updated Event

Event archivieren

• DELETE /api/v1/tenant/events/{slug}
  • Headers: Authorization: Bearer {token}, If-Match: {etag}
  • Response: 204 No Content (soft-delete)

Photos

Photos laden

• GET /api/v1/tenant/events/{event_id}/photos
  • Headers: Authorization: Bearer {token}
  • Params:
    • page=1, per_page=50
    • status=pending|approved|rejected|featured
    • sort=date|likes
    • since=cursor (für Infinite Scroll)
  • Response: { data: Photo[], current_page, last_page }
  • Photo-Shape: { id, eventId, url, thumbnail, uploadedAt, status, likes, views, uploader, etag }

Upload-URL anfordern

• POST /api/v1/tenant/events/{event_id}/photos
  • Headers: Authorization: Bearer {token}, Content-Type: application/json
  • Body: { file_name, description? }
  • Response: { id, upload_url (S3 signed), thumbnail_url }

Photo moderieren

• PATCH /api/v1/tenant/photos/{id}
  • Headers: Authorization: Bearer {token}, Content-Type: application/json, If-Match: {etag}
  • Body: { status: 'approved'|'rejected'|'featured', featured?, reason? }
  • Response: Updated Photo

Photo löschen

• DELETE /api/v1/tenant/photos/{id}
  • Headers: Authorization: Bearer {token}, If-Match: {etag}
  • Response: 204 No Content

Members

Mitglieder laden

• GET /api/v1/tenant/events/{event_id}/members
  • Headers: Authorization: Bearer {token}
  • Params: page, per_page, status=pending|active|invited
  • Response: { data: Member[], current_page, last_page }
  • Member-Shape: { id, name, email, role, joinedAt, avatar?, status }

Mitglied einladen

• POST /api/v1/tenant/events/{event_id}/members
  • Headers: Authorization: Bearer {token}, Content-Type: application/json
  • Body: { email, role: 'member'|'guest', name? }
  • Response: 201 Created, E-Mail wird versendet

Tasks

Tasks laden

• GET /api/v1/tasks
  • Headers: Authorization: Bearer {token}
  • Params:
    • global=true/false (globale vs. tenant Tasks)
    • tenant_id=me (nur eigene Tasks)
    • category=setup|photo|event|cleanup
  • Response: { data: Task[], global: boolean }
  • Task-Shape: { id, title, description?, category, isGlobal, tenantId?, createdAt, color? }

Event-Tasks laden

• GET /api/v1/tenant/events/{event_id}/tasks
  • Headers: Authorization: Bearer {token}
  • Response: { data: EventTask[], overall_progress }
  • EventTask-Shape: { id, eventId, taskId, task: Task, order, completed, assignedTo?, progress }

Tasks bulk zuweisen

• POST /api/v1/tenant/events/{event_id}/tasks/bulk
  • Headers: Authorization: Bearer {token}, Content-Type: application/json
  • Body: { task_ids: string[], order: number[] }
  • Response: Updated EventTasks mit neuer Reihenfolge

Settings

Settings laden

• GET /api/v1/tenant/settings
  • Headers: Authorization: Bearer {token}
  • Response: { primaryColor, tenantName, maxEventsPerMonth, enableTasks, enableEmotions, legalPages { impressumUrl, privacyUrl } }

Settings updaten

• PATCH /api/v1/tenant/settings
  • Headers: Authorization: Bearer {token}, Content-Type: application/json
  • Body: Partial Settings-Daten
  • Response: Updated Settings

Billing

Balance laden

• GET /api/v1/tenant/credits/balance
  • Headers: Authorization: Bearer {token}
  • Response: { balance: number }

Ledger-Verlauf

• GET /api/v1/tenant/credits/ledger
  • Headers: Authorization: Bearer {token}
  • Params: page, per_page (Pagination)
  • Response: { data: LedgerEntry[], current_page, last_page }
  • LedgerEntry: { id, type, amount, credits, date, description, transactionId? }

Credits kaufen (In-App)

• POST /api/v1/tenant/credits/purchase
  • Headers: Authorization: Bearer {token}, Content-Type: application/json
  • Body: { package_id: string, credits_added: number, platform?: 'capacitor'|'web', transaction_id?: string, subscription_active?: boolean }
  • Response: { message, balance, subscription_active }
  • Hinweis: Wird nach erfolgreichen In-App-Kuferfolgen aufgerufen, aktualisiert Balance & Ledger.

Credits synchronisieren

• POST /api/v1/tenant/credits/sync
  • Headers: Authorization: Bearer {token}, Content-Type: application/json
  • Body: { balance: number, subscription_active: boolean, last_sync: ISODateString }
  • Response: { balance, subscription_active, server_time }
  • Hinweis: Client meldet lokalen Stand; Server gibt Quelle-der-Wahrheit zurcck.

Kauf-Intent erstellen

• POST /api/v1/tenant/purchases/intent
  • Headers: Authorization: Bearer {token}, Content-Type: application/json
  • Body: { package_id }
  • Response: { checkout_url: string } (Stripe-Checkout)
  • Nach dem Kauf: Webhook-Handling auf Backend für Balance-Update

Allgemeine Headers

Alle API-Requests enthalten:

• Authorization: Bearer {access_token} (Sanctum PAT mit Fähigkeit tenant:{id})
• Content-Type: application/json (für POST/PATCH)
• If-Match: {etag} (für Concurrency-Control bei Updates)
• Accept: application/json

Error-Handling

Standard-Error-Response:

{
  "error": {
    "code": "PACKAGE_LIMIT_EXCEEDED",
    "message": "Package-Limit überschritten (z.B. max_photos)"
  }
}

HTTP Status Codes:

• 200: Erfolg
• 201: Created
• 400: Bad Request (Validierungsfehler)
• 401: Unauthorized (Token-Refresh wird versucht)
• 403: Forbidden (RBAC-Verletzung)
• 404: Not Found
• 422: Unprocessable Entity
• 429: Rate Limited (Client retry mit Backoff)

Pagination

Alle Listen-Endpunkte unterstützen:

• page: Aktuelle Seite (default 1)
• per_page: Einträge pro Seite (default 20, max 50 für Mobile)
• Response: { data: [], current_page, last_page, per_page, total }

Headers für Concurrency

Mutierende Endpunkte (PATCH/DELETE) erfordern:

• If-Match: {etag} aus GET-Response
• Response: 412 Precondition Failed bei Conflict

Sicherheit

• Tenant-Isolation: Middleware vergleicht PAT-Fähigkeit (tenant:{id}) mit dem angefragten Tenant
• RBAC: Nur tenant_admin kann mutieren, member kann nur lesen/hochladen
• Rate Limiting: 100 Requests/Minute pro Tenant
• ETag: Automatische Concurrency-Control
• No PII-Logging: Keine sensiblen Daten in Logs

Testing

API-Test-Setup

1. Backend starten: Stelle sicher, dass die Hauptapp läuft und Endpunkte verfügbar sind.
2. Token erzeugen: Verwende Postman mit gültigem Access-Token.
3. Endpoints testen: Jeder Endpunkt einzeln mit curl oder Postman.

Beispiel curl (mit Token)

curl -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  https://api.fotospiel.com/api/v1/tenant/events

Frontend-Test

1. .env mit korrekter API-URL konfigurieren.
2. npm run dev starten.
3. Browser-Network-Tab überprüfen für API-Calls.

Deployment

Environment-Variablen

• VITE_API_URL: Backend-API-URL (Pflicht)
• VITE_ENABLE_TENANT_SWITCHER: Dev-Flag um Tenants im Header auszuwählen (optional, Default false)
• VITE_REVENUECAT_PUBLIC_KEY: Optional für In-App-Käufe (RevenueCat)
• SANCTUM_STATEFUL_DOMAINS (Backend): Enthält die Origins des Admin-PWA/TWA, damit der Session→PAT-Exchange funktioniert.
• REVENUECAT_WEBHOOK_SECRET / REVENUECAT_PRODUCT_MAPPINGS / REVENUECAT_APP_USER_PREFIX / REVENUECAT_WEBHOOK_QUEUE: Backend-Konfiguration für RevenueCat-Webhooks, siehe config/services.php.

Build & Deploy

1. Development: npm run dev
2. Production: npm run build
3. Vorschau: npm run preview

PWA-Installation

• App ist PWA-fähig (Manifest, Service Worker).
• Installierbar auf Desktop/Mobile via "Zum Startbildschirm hinzufügen".

Für weitere Details siehe die spezifischen Dokumentationsdateien.