Tickets

Ein Ticket ist einer der Produkt-Typen in go~mus (z.B. Tickets, Tours, Events) und steht für Eintrittstickets im weiteren Sinn - also alles, was Besucher:innen im Haus eingelassen wird. Wenn du einst Online-Shop, eine Webseite mit Buchungsstrecke oder ein Reseller-System anbindet, sind Tickets in der Regel der erste Touchpoint.

Diese Seite erklärt das Mental-Modell und die häufigsten Workflows. Vollständige Endpoint- und Schema-Referenz: Swagger.

Ticket-Typen

go~mus kennt drei Typen, die sich in Verfügbarkeitslogik und Pflichtparametern unterscheiden:

`ticket_type`	Wann	Verfügbarkeit prüfen über
`normal`	Eintritt an einem Datum, kein Zeitfenster (Tagesticket)	`capacity` - eine Zahl pro Tag
`time_slot`	Eintritt in einem Slot (z.B. 14:00-14:30)	`capacities` - Array von Slots pro Tag
`annual`	Jahreskarten - eigener Endpoint und Lebenszyklus, siehe Annual Tickets	n/a

Orthogonal dazu gibt es Flex-Tickets: Tickets mit free_timing: true werden ohne festes Datum verkauft und sind innerhalb ihrer Gültigkeit jederzeit einlösbar. Funktional fast immer eine Variante von normal. Filter: ?by_free_timing=true.

bookable: true filtert auf öffentlich buchbar für deine Auth-Stufe (Public-Token, Reseller-Token, Cash-Point-Token sehen je nach Konfiguration unterschiedliche Sets).

Anatomie eines Ticket-Objekts

Im Index- und Detail-Response findest du je Ticket diese Felder regelmäßig:

id - stabiler Primärschlüssel, nutzt das in Order-Items, Cart-States und als foreign key auf eurer Seite
title, description - übersetzbar via ?locale=de (siehe Konzepte: Locale)
ticket_type - siehe oben
price_cents, vat_pct, tax_included - Basis-Preis. Preisregeln (Mitglieder-Rabatt, Zeit-Pricing) modifizieren das ggf. erst auf Order-Item-Ebene
quota_ids - auf welche Kontingente das Ticket zugreift (siehe Konzepte: Quotas)
museum_ids, exhibition_ids - Zuordnung zu Häusern und Sonderausstellungen
entry_duration - bei time_slot: Slot-Länge in Minuten. Bei normal immer null
free_timing - Boolean. true = Flex-Ticket (kein festes Datum bei Verkauf)
min_persons, max_persons - Bestellgrenzen pro Buchung

Komplette Feldliste inklusive Personalisierung, Attendee-Pflicht und Validierungs-Flags: Swagger.

Endpoints im Überblick

Endpoint	Wofür	Wann nutzen
`GET /api/v4/tickets`	Liste mit Basis-Daten	Übersicht, Filter, Suche
`GET /api/v4/tickets/:id`	Detail eines Tickets	Volle Beschreibung, Konfiguration
`GET /api/v4/tickets/:id/capacity`	Restplätze für ein Datum (Map Slot → Anzahl)	"Noch X Tickets übrig" pro Slot
`GET /api/v4/tickets/calendar?ticket_ids[]=...`	Buchbarkeit pro Tag im Zeitraum	Datepicker, ausverkaufte Tage ausgrauen
`GET /api/v4/tickets/capacities?ticket_ids[]=...`	Capacities mehrerer Tickets, gruppiert nach Quota	Slot-Liste über mehrere Tickets gleichzeitig
`POST /api/v4/tickets/reservations`	Plätze temporär blocken	Vor dem Order-Finalize
`PUT /api/v4/tickets/reservations/:token`	Menge ändern und Lebensdauer verlängern	Während die Nutzer:in im Checkout ist
`DELETE /api/v4/tickets/reservations/:token`	Reservation freigeben	Wenn Nutzer:in abbricht

Häufige Aufgaben

Tickets auflisten

curl "https://demo.gomus.de/api/v4/tickets?by_bookable=true&locale=de"

Häufig genutzte Filter:

by_museum_ids[]=20&by_museum_ids[]=21 - nur Tickets bestimmter Häuser
by_exhibition_ids[]=2057 - nur Tickets einer Sonderausstellung
by_ticket_type=time_slot - nur Zeitfenster-Tickets (oder normal, annual)
by_free_timing=true - nur Flex-Tickets
valid_at=2026-09-01 - Ticket-Set, das an diesem Stichtag aktiv ist (Default: heute)

Ein Ticket im Detail abfragen

curl "https://demo.gomus.de/api/v4/tickets/247?locale=de"

Detail-Response enthält gegenüber dem Index die volle description, ggf. zusätzliche Konfigurationsfelder und vollständige Preis-Information.

Verfügbarkeit prüfen - ein einzelnes Ticket

curl "https://demo.gomus.de/api/v4/tickets/247/capacity?date=2026-05-15"

Response-Shape:

{
  "data": {
    "2026-05-15T11:00:00+02:00": 15,
    "2026-05-15T11:30:00+02:00": 21
  }
}

Map von Slot-Startzeit auf Restplätze. Bei time_slot-Tickets ein Eintrag pro Slot, bei normal typisch ein einzelner Eintrag (Tagesöffnungszeit). Capacity berücksichtigt alle Quotas, denen das Ticket zugeordnet ist - bei Kombi-Tickets ist das Ergebnis das Minimum.

Verfügbarkeit über mehrere Tickets gleichzeitig

curl "https://demo.gomus.de/api/v4/tickets/capacities?ticket_ids[]=247&ticket_ids[]=248&date=2026-05-15"

Liefert die Capacities gruppiert nach Quota-ID, mit total_capacities (konfiguriertes Maximum) und capacities (aktuell verfügbar). Praktisch, um im Checkout Restplätze konsistent über mehrere Tickets darzustellen, die sich Quotas teilen.

Verfügbare Tage finden (Datepicker)

curl "https://demo.gomus.de/api/v4/tickets/calendar?ticket_ids[]=247&start_at=2026-05-01&end_at=2026-05-31"

Liefert pro Tag ein Boolean - praktisch um in einem Datepicker ausverkaufte Tage auszugrauen, ohne pro Tag eine capacity-Anfrage zu machen. Maximal 31 Tage pro Call. Mit depth=all statt dem Default any kommt zusätzlich die Quota- und Capacity-Information pro Tag mit.

Eine Reservation erstellen

curl -X POST "https://demo.gomus.de/api/v4/tickets/reservations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reservation": {
      "ticket_id": 247,
      "quantity": 2,
      "start_at": "2026-05-15T14:00:00+02:00"
    }
  }'

Response enthält einen token - den nutzt du für PUT/DELETE und im finalen Order-Item, damit die Plätze tatsächlich an eurer Bestellung hängen.

Eine Reservation refreshen oder Menge ändern

curl -X PUT "https://demo.gomus.de/api/v4/tickets/reservations/RESERVATION_TOKEN" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reservation": { "quantity": 3 } }'

PUT verlängert gleichzeitig die Lebensdauer. Wenn du eine Nutzer:in im Checkout halten wollen während sie länger braucht, kannst du dasselbe quantity ein zweites Mal senden - das verschiebt das Ablaufdatum nach hinten.

Eine Reservation freigeben

curl -X DELETE "https://demo.gomus.de/api/v4/tickets/reservations/RESERVATION_TOKEN" \
  -H "Authorization: Bearer YOUR_TOKEN"

Wichtig vor allem bei Abbruch im Checkout - sonst halten die Plätze bis zum Ablauf der Reservation, und andere Nutzer:innen sehen sie als "ausverkauft".

Beziehungen

Ticket
 ├── Quota (1..n) ......... bestimmt die Verfügbarkeitslogik
 ├── Museum (1..n) ........ zu welchen Häusern das Ticket gehört
 ├── Exhibition (0..n) .... zu welchen Sonderausstellungen
 ├── Reservation (0..n) ... temporäre Platzhalter
 └── OrderItem ............ wenn gebucht, landet das Ticket als Item in einer Order

Ein Ticket kann mehrere Quotas referenzieren. Das ist häufig bei Kombi-Tickets - das Ticket "Sammlung plus Sonderausstellung" zieht Plätze aus zwei Quota-Pools gleichzeitig. Die Verfügbarkeit ist dann das Minimum.

Stolperdrahte

valid_at ist der Stichtag, nicht das Buchungsdatum. Default ist heute. Wenn du Tickets auflisten, die in 6 Monaten gelten sollen (Vorverkauf einer Sonderausstellung), setzt du valid_at entsprechend, sonst siehst du nur, was am heutigen Tag aktiv ist.
bookable ist kontextabhängig. Mit Public-Token siehst du bookable: true für Tickets, die Walk-in-Käufer:innen kaufen können. Mit Reseller-Token kann das Set anders aussehen - manche Tickets sind öffentlich bookable: false, für Reseller aber sehr wohl buchbar. Das ist Absicht und konfigurationsabhängig.
capacity (singular) und capacities (plural) sind nicht austauschbar. Singular liefert eine Zahl für einen Tag (Tagesticket), Plural liefert ein Array von Slots (Zeitfenster-Ticket). Falscher Endpoint = entweder leeres Array oder bedeutungslose Zahl.
Capacities sind Live-Daten - bitte nicht cachen. Eine 30 Sekunden alte Capacity ist beim Buchungsversuch womöglich falsch, du läufst am Ende in einen Konflikt im Order-Finalize.
Reservation-Token ist die ID. Für PUT und DELETE nutzt du den token aus dem Create-Response, nicht die numerische ID des Tickets.
Reservation hat eine begrenzte Lebensdauer. Default ist instance-spezifisch (Größenordnung Minuten). Plant Refresh ein, wenn dein Checkout länger dauern kann (z.B. Login + Adresseingabe + Payment). Details in Reservations (Seite folgt).