Events (Veranstaltungen)

Ein Event ist in go~mus eine Veranstaltung wie ein Workshop, eine Führung im Vortragssaal oder ein Kinderprogramm - alles, was zu einem konkreten Termin stattfindet und gebucht werden kann. Ein Date ist die einzelne Terminausführung dieses Events. Ein Event hat in der Regel viele Dates über die Zeit verteilt; auf der Webseite zeigst du meistens Dates, nicht Events.

Der häufigste Einsatzzweck dieser Resource ist der Veranstaltungskalender auf der Museumswebseite: eine Liste aller buchbaren Termine, optional gefiltert nach Haus, Sonderausstellung, Zielgruppe oder Sprache, mit Link von jedem Eintrag in den Buchungsvorgang.

Vollständige Endpoint- und Schema-Referenz: Swagger.

Event vs Date - das Mental-Modell

Begriff	Was	Beispiel
Event	Veranstaltungs-Schablone	"Sonntagsführung durch die Sammlung"
Date	Konkrete Ausführung mit Datum/Uhrzeit	"Sonntag, 18.05. um 11:00"

Auf der Webseite werden Dates (Termine) gelistet, die Besucher:in klickt sich durch, kommt am Ende auf die Bestellung eines bestimmten Dates. Ein Event allein ist nicht buchbar - immer das Date.

Anatomie eines Event-Objekts

Im Index- und Show-Response findest du je Event:

id - stabil, nutzt das überall
title, sub_title, description - übersetzbar via ?locale=de
museum_id, exhibition_id - Zuordnung
category - eingebettetes Kategorie-Objekt (siehe Filter unten)
bookable, registerable - kontextabhängige Flags für deine Auth-Stufe
featured - Boolean, ob das Event im Frontend hervorgehoben werden soll
min_persons, max_persons, max_participants - Bestellgrenzen und Gesamtkapazität
duration - Dauer in Minuten
entry_fee - Modus für Eintrittsgebühr-Anzeige (auto / included / excluded / none)
upcoming_bookings_start_times - eingebettete Liste der nächsten freien Startzeiten dieses Events. Sehr nützlich für Listings: du kannst "Nächster Termin: Sa 18.05. um 11:00" direkt in der Event-Übersicht anzeigen, ohne pro Event einen zweiten Roundtrip auf dates oder calendar zu machen.

Im Show-Response zusätzlich: eingebettete dates (kommende Termine), tickets (zugehörige Ticket-Konfigurationen), quotas, content (Langtexte), documents (Anhänge).

Komplette Feldliste: Swagger.

Anatomie eines Date-Objekts

Die Date-Resource ist absichtlich schmal - die meisten Anzeigedaten kommen vom dahinterliegenden Event:

id - stabil, nutzt das im Order-Item
event_id - Rückverweis auf das Event
status - booked (bestätigt und stattfindend) oder cancelled
language - eingebettet, mit Code und Bezeichnung
location - eingebettet, falls Event ortsspezifisch
prices - Liste mit Preis-Varianten für dieses Date
start, ende - Start- und Endzeit (ISO-8601)
category, duration, entry_fee - vom Event durchgereicht

Endpoints im Überblick

Endpoint	Wofür	Wann nutzen
`GET /api/v4/events`	Event-Liste	Übersicht aller Veranstaltungen, mit Filtern
`GET /api/v4/events/:id`	Event-Detail	Volle Beschreibung inklusive nächster Dates
`GET /api/v4/events/:event_id/calendar`	Kalender für ein Event	"Welche Termine gibt es für dieses eine Event?"
`GET /api/v4/events/:event_id/dates`	Dates eines Events	Liste der Ausführungen mit Detail
`GET /api/v4/events/:event_id/dates/:id`	Einzelnes Date	Zeit, Sprache, Preise eines konkreten Termins
`GET /api/v4/dates`	Globaler Kalender	Veranstaltungskalender über alle Events hinweg
`GET /api/v4/events/:event_id/categories`	Kategorien des Events	für Filter-UI
`GET /api/v4/events/:event_id/languages`	Verfügbare Sprachen	für Filter-UI
`GET /api/v4/events/:event_id/audiences`	Zielgruppen	für Filter-UI
`GET /api/v4/events/:event_id/age_groups`	Altersgruppen	für Filter-UI

Häufige Aufgaben

Veranstaltungskalender bauen (der Hauptanwendungsfall)

Der Endpoint, der dafür gemacht ist: GET /api/v4/dates. Er liefert Dates über alle Events hinweg in einem Zeitfenster, nach denselben Filtern, mit denen sich Events filtern lassen.

curl "https://demo.gomus.de/api/v4/dates?start_at=2026-05-01&end_at=2026-05-31&locale=de"

Default für start_at ist heute, Default für end_at ist Ende des Startmonats.

Kombinierbare Filter (alle optional):

by_museum_ids[]=20 - nur Termine eines Hauses
by_exhibition_ids[]=2057 - nur Termine zu einer Sonderausstellung (-1 für "ohne Ausstellungsbezug")
by_event_ids[]=843 - nur Termine bestimmter Events
by_category_ids[]=12 oder by_categories[]=fuehrung - Kategorie-Filter
by_audience_ids[]=4 - z.B. nur Termine für Familien
by_age_group_ids[]=2 - z.B. nur Termine für Erwachsene
by_grade_ids[]=8 - z.B. Schulklassen-Stufe
by_language_ids[]=1 - nur deutschsprachige Termine
by_catch_word_ids[], by_disablement_ids[], by_proposal_category_ids[] - weitere Klassifikationen
by_bookable=true - nur tatsächlich buchbare Termine

Die Antwort enthält pro Date Status, Zeit, Event-Verweis, Sprache und Preise - genug für eine Listendarstellung. Für Detail-Klicks dann auf das Date oder das Event verlinken.

Event-Liste mit Filtern

curl "https://demo.gomus.de/api/v4/events?by_museum_ids[]=20&by_audience_ids[]=4&with_bookings_in_future=true&locale=de"

with_bookings_in_future=true ist nützlich, um nur Events anzuzeigen, die überhaupt noch kommende Termine haben.

Filter-UI mit den verfügbaren Werten füllen

Statt fest verdrahteter Dropdowns holt dir die aktuell relevanten Filterwerte:

curl "https://demo.gomus.de/api/v4/events/categories?locale=de"
curl "https://demo.gomus.de/api/v4/events/audiences?locale=de"
curl "https://demo.gomus.de/api/v4/events/languages?locale=de"

Diese Endpoints liefern jeweils nur die Werte, die in der Instance tatsächlich genutzt werden - sauber für eine Filter-Sidebar.

Event im Detail mit eingebetteten Dates

curl "https://demo.gomus.de/api/v4/events/843?locale=de"

Show-Response liefert die Beschreibung sowie die nächsten kommenden Dates direkt mit, sodass eine Detail-Seite ohne zweiten Roundtrip auskommt.

Termine eines konkreten Events

curl "https://demo.gomus.de/api/v4/events/843/dates?start_at=2026-05-01&end_at=2026-12-31"

Wenn du für ein einzelnes Event eine Termin-Übersicht bauen.

Vom Date zur Buchung - die vier Wege

Sobald ein/e Besucher:in auf einen Termin klickt, gibt es je nach Setup vier Optionen:

1. Verlinkung in den Shop

Wenn das Museum einen go~mus-Shop nutzt, hat jedes Event/Date eine kanonische Shop-URL. Die einfachste Lösung: vom Kalender direkt dorthin verlinken. Der Shop übernimmt Auswahl, Personenzahl, Optionen und Bezahlung.

2. Webcomponents im eigenen Frontend

Wenn du den Buchungsvorgang im Layout der Museumswebseite haben wollen, ohne in einen Shop zu springen: die go~mus Webcomponents decken Date-Auswahl, Personenzahl, Checkout und Payment ab. Volle CSS-Kontrolle, kein Iframe.

3. Direktbuchung über die API (POST Order + Finalize)

Wenn du den kompletten Buchungsfluss selbst implementiert (so machen es z.B. der Museumsdienst Berlin auf der Webseite): zwei Calls genügen.

Erst eine Order anlegen mit dem Date als Item:

curl -X POST "https://demo.gomus.de/api/v4/orders" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "items": [
        { "date_id": 91234, "quantity": 2 }
      ],
      "customer": { "email": "kund@example.com", "..." : "..." }
    }
  }'

Dann finalisieren - das löst Bestätigungsmail, Barcode-Erzeugung und Backoffice-Eintrag aus:

curl -X POST "https://demo.gomus.de/api/v4/orders/ORDER_TOKEN/finalize" \
  -H "Authorization: Bearer YOUR_TOKEN"

Genaue Payload-Strukturen, Validierungen und Payment-Optionen: Swagger und Best Practices.

Für einfache Fälle gibt es Iframe-basierte Widgets - schneller eingebunden, weniger Layout-Kontrolle.

Beziehungen

Event
 ├── Date (1..n) ......... konkrete Ausführungen
 │    ├── Language ....... Vortragssprache
 │    ├── Location ....... Ort, falls vom Event abweichend
 │    └── Prices ......... Preis-Varianten dieses Termins
 ├── Museum .............. Haus
 ├── Exhibition (0..1) ... Sonderausstellung
 ├── Category ............ z.B. Führung, Workshop, Vortrag
 ├── Audience (0..n) ..... z.B. Familien, Schulklassen
 ├── AgeGroup (0..n) ..... z.B. Kinder, Erwachsene
 ├── Language (0..n) ..... welche Sprachen werden ausgeführt
 └── OrderItem (über Date) wenn gebucht

Buchungs-Primitiv ist immer das Date - nie das Event.

Stolperdrahte

Globaler Kalender vs Per-Event-Kalender. Für die Webseite-Liste über alle Veranstaltungen: GET /api/v4/dates. Für eine Detail-Seite eines einzelnen Events: GET /api/v4/events/:id (mit eingebetteten Dates) oder GET /api/v4/events/:event_id/dates.
Reservation-Endpoint nur für öffentliche Touren-Bookings. POST /api/v4/events/reservations existiert (mit event_id = Booking-ID, quantity), funktioniert aber nur für Bookings, die als öffentliche Tour (Einzelangebot) konfiguriert sind. Reine Events ohne Tour-Anbindung haben keinen Reservation-Hold - hier werden Plätze beim Order-Create direkt belegt. Entsprechend wichtig: sauberes Error-Handling beim Finalize.
by_status nur für Content-API-User. Default ist booked - abgesagte Termine erscheinen in normalen Listen nicht. Wer abgesagte Dates braucht, ruft mit by_status=cancelled auf, aber das geht nur mit einem Content-API-User-Token.
start_at / end_at haben Defaults. Ohne Parameter wird "ab heute bis Ende des Monats" geliefert. Für einen 12-Monats-Kalender setzt du beide explizit.
Kategorie-Filter haben zwei Varianten. by_category_ids[] filtert über die numerische ID, by_categories[] über den filtername-String der Kategorie. Letzteres ist robuster gegen ID-Änderungen über Instances hinweg.
exhibition_id = -1 im Filter ist eine Sonderform: damit erhältst du Termine, die keiner Sonderausstellung zugeordnet sind. Praktisch für "Sammlungs-Veranstaltungen".