# Gäste-Import und Empfehlungen

Anmeldungen per CSV importieren und Empfehlungscodes für Gäste nutzen.

## Hinweise für KI-Agenten

- API-Basisadresse: `https://api.eventwerk.eu/api/v1`
- OpenAPI 3.1: `https://api.eventwerk.eu/openapi.json` und `/api/v1/openapi.json`. Daraus lassen sich Clients und Typprüfungen generieren.
- Anmeldung: `Authorization: Bearer ew_...`
- Schlüssel: Einstellungen unter `/dashboard/einstellungen`, nur mit Eventwerk Plus und nur für Eigentümer. Der volle Schlüssel wird nur einmal angezeigt. Name und Zeitpunkt der letzten Nutzung werden geführt und ausgegeben.
- Zeiten: Alle Zeitpunkte kommen in UTC mit Suffix `Z`. Die Zeitzone des Events steht getrennt in `timezone` als IANA-Name, Standard `Europe/Vienna`. Clients rechnen selbst um.
- Paginierung: Die Event- und Anmeldelisten liefern `{items, has_more, next_cursor}` mit `limit` (Standard 50, höchstens 200), `cursor` und `updated_since`.
- Grenzen: 200 Anfragen pro Minute je Schlüssel. Der Zähler liegt im Speicher je Instanz, ist hinter mehreren Instanzen ein Vielfaches und beginnt nach einem Deploy neu. Bei Überschreitung antwortet die API mit 429, `rate_limited` und `Retry-After`.
- Gastgrenzen: Anmelde-Link 20 je Stunde je IP-Adresse, Anmeldung 60 je Stunde je IP-Adresse und 3 je Stunde je E-Mail-Adresse und Event.
- Fehler: JSON mit `code` und `message`, optional mit `details`.

Neben der Gästeliste und dem CSV-Export gibt es den CSV-Import und Empfehlungscodes. Beide laufen über die Sitzungs-API und sind nicht Teil der öffentlichen API unter `/api/v1`.

## CSV-Import

Die Vorlage liegt unter `GET /api/events/{eventID}/registrations/import/template.csv`. Sie enthält ein Byte Order Mark und die Spalten name, email, ticket, promo_code und referral_code.

- `POST /api/events/{eventID}/registrations/import/preview` prüft die Datei, ohne etwas zu speichern.
- `POST /api/events/{eventID}/registrations/import` legt die gültigen Zeilen an.
- Die Datei wird als Multipart-Feld file gesendet.
- Erlaubt sind höchstens 2 MB und 5000 Datenzeilen.
- Pflicht sind die Spalten name und email. Weitere Spalten sind optional.
- Doppelte E-Mail-Adressen in der Datei und bereits vorhandene Anmeldungen werden übersprungen.
- Unbekannte oder leere Ticketnamen verwenden die Ticketart Standard. Fehlt diese, schlägt die Zeile mit `ticket_not_found` fehl.
- Ungültige Namen oder E-Mail-Adressen erscheinen als Fehler mit Zeilennummer.
- Bei Events mit Zugangscode wird jede Zeile mit `access_code_required` abgelehnt.
- Importierte Gäste erhalten keine E-Mail.

Die Antwort des Imports enthält `created`, `skipped`, `failed`, `errors` und `note`. Die Vorschau liefert `columns`, die ersten 10 `rows`, `errors` und `total_rows`.

> **Hinweis:** Die Vorschau speichert nichts. Eine eigene Oberfläche für den Import ist noch nicht gebaut; die Verwaltung läuft über die API.

## Empfehlungscodes

Jede Anmeldung kann einen Empfehlungscode erhalten. Der Code gilt nur für das Event und ist acht Zeichen lang. Ein erneuter Aufruf liefert denselben Code. Die Antwort enthält `referral_code` und `share_url`.

| Methode | Pfad | Zweck |
| --- | --- | --- |
| POST | /api/events/{eventID}/registrations/{registrationID}/referral | Empfehlungscode erzeugen oder lesen. |
| GET | /api/events/{eventID}/referrals | Empfehlungen mit eingeladenen und angemeldeten Personen lesen. |

Die geteilte Adresse lautet `/e/<slug>?ref=<code>`. Bei der öffentlichen Anmeldung wird der Code als `referral_code` mitgeschickt. Ein unbekannter Code bricht die Anmeldung nicht ab; die Zuordnung fehlt dann.

- Der Empfehlungscode steht in der Gästeliste bei der eingeladenen Anmeldung.
- Die Auswertung enthält `referrer_name`, `referrer_email`, `code`, `invited_count` und `registered_count`.
- `invited_count` zählt offene, bestätigte und wartende Anmeldungen, `registered_count` nur bestätigte.
- Alle Endpunkte dieser Seite brauchen ein Sitzungs-Token und die Rolle Eigentümer oder Verwaltung.

> **Hinweis:** Die öffentliche Anmeldung im Frontend sendet derzeit keinen Empfehlungscode mit. Die Zuordnung ist über die API möglich. Eine Oberfläche für Empfehlungen ist noch nicht gebaut.