# Tickets

Ticketarten, Kontingente, Preise und Promo-Codes.

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

Jedes Event erhält beim Anlegen automatisch eine freie Ticketart mit dem Namen Standard. Sie hat kein Kontingent, ist aktiv und nicht verborgen. Weitere Ticketarten legen Sie im Dashboard unter dem Event an.

## Felder einer Ticketart

| Feld | Bedeutung |
| --- | --- |
| name | Name der Ticketart, höchstens 200 Zeichen. |
| description | Beschreibung für die öffentliche Seite. |
| price_cents | Preis in Cent, nie negativ. 0 bedeutet kostenlos. |
| currency | Dreistelliger Währungscode, Standard EUR. |
| quantity | Kontingent. null bedeutet unbegrenzt. |
| min_per_order | Mindestanzahl pro Bestellung, Standard 1. |
| max_per_order | Höchstanzahl pro Bestellung, Standard 10. |
| hidden | Verbirgt die Ticketart auf der öffentlichen Seite. |
| is_donation | Kennzeichnet eine Spenden-Ticketart. |
| active | Nur aktive Ticketarten sind öffentlich sichtbar. |
| sort_order | Reihenfolge in der Anzeige. |

## Öffentliche Anzeige

Öffentlich erscheinen nur aktive Ticketarten, die nicht verborgen sind. Das verbleibende Kontingent ergibt sich aus dem Kontingent minus der Anmeldungen mit Status pending oder confirmed. Zusätzlich kann die Kapazität des Events die Anmeldung begrenzen.

## Preise und Bezahlung

Kostenlose Tickets führen zu einer bestätigten Anmeldung, solange ein Platz frei ist. Ist ein Preis größer als null und kein rabattierender Promo-Code gesetzt, antwortet die Anmeldung mit `payment_not_available`. Kartenzahlung und regionale Zahlungsmethoden sind geplant, aber noch nicht gebaut.

> **Warnung:** Kostenpflichtige Tickets sind derzeit nicht buchbar. Bewerben Sie deshalb nur kostenlose Ticketarten.

## Promo-Codes

Promo-Codes reduzieren den Preis einer Ticketart. Ein Code gilt immer für ein Event. Er wird bei der Anmeldung zusammen mit dem Ticket angegeben.

| Feld | Bedeutung |
| --- | --- |
| code | Code, höchstens 64 Zeichen. Wird in Großbuchstaben gespeichert. |
| discount_type | percent, fixed oder free. |
| amount | Bei percent zwischen 1 und 100, bei fixed der Rabatt in Cent, bei free wird 0 gespeichert. |
| max_redemptions | Maximale Einlösungen. null bedeutet unbegrenzt. |
| expires_at | Ablaufzeitpunkt als RFC-3339-Zeitpunkt. |

- Der berechnete Preis ist nie negativ.
- Ein Prozentrabatt wird abgerundet.
- Ein Code mit dem Typ free macht ein kostenpflichtiges Ticket kostenlos und damit buchbar.
- Die maximale Einlöseanzahl darf nicht unter die bereits erreichten Einlösungen gesetzt werden.

## Löschen und pausieren

Eine Ticketart mit Anmeldungen kann nicht gelöscht werden. Stattdessen setzen Sie sie auf inaktiv oder verborgen. Eine ungenutzte Ticketart lässt sich löschen.