# Umfragen

Umfragen anlegen, öffnen, beantworten und auswerten.

## 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`.

Umfragen gehören zu einem Event. Sie können im Entwurf vorbereitet, geöffnet und später geschlossen werden. Antworten sind anonym, solange kein Ticket-Token mitgeschickt wird.

## Status

| Status | Bedeutung |
| --- | --- |
| draft | Entwurf. Fragen lassen sich bearbeiten. |
| open | Offen. Die Umfrage ist öffentlich erreichbar und nimmt Antworten an. |
| closed | Geschlossen. Es werden keine Antworten mehr angenommen. |

Fragen lassen sich nur im Entwurf ändern. Eine offene Umfrage zeigt ihre Fragen unverändert an. Öffentlich erreichbar ist eine Umfrage nur, wenn sie offen ist und das Event veröffentlicht wurde.

## Fragetypen

| Typ | Antwort |
| --- | --- |
| single | Genau eine Option. |
| multi | Mehrere Optionen, ohne Doppelte. |
| text | Freitext. |
| scale | Ganze Zahl zwischen zwei Grenzen. Die Grenzen stehen als zwei Optionen mit numerischen Schlüsseln in der Frage. |

## Teilnahme

Der öffentliche Link lautet `/e/<slug>/umfrage/<surveyId>`. Auf der Ticketseite verlinkt Eventwerk offene Umfragen mit dem Ticket-Token als Parameter `t`.

- Mit gültigem Ticket-Token wird die Antwort mit der Anmeldung verknüpft.
- Pro Anmeldung ist eine Teilnahme möglich. Eine zweite Antwort ergibt `already_responded`.
- Ohne Token oder mit unbekanntem Token wird die Antwort gespeichert, aber nicht mit einer Anmeldung verknüpft.
- Pflichtfragen müssen beantwortet werden, sonst antwortet die API mit `question_required`.
- Optionen müssen zur Frage gehören, sonst antwortet die API mit `invalid_option`.

## Auswertung

Die Ergebnisse zeigen die Zahl der Teilnahmen und je Frage die Verteilung. Einfach- und Mehrfachauswahl liefern Anzahl und Prozent je Option. Textfragen liefern die Texte. Skalen liefern Minimum, Maximum, Durchschnitt und die Verteilung der Werte.

> **Hinweis:** Eine Umfrage ist kein Pflichtformular. Gäste können sie auch ohne Anmeldung beantworten, wenn der Link geteilt wird. Mit Ticket-Token bleibt die Teilnahme dagegen eindeutig.