Webseiten-Integration

Eine Museums-Webseite an go~mus anbinden - Veranstaltungskalender, Direkt-Anmeldung, Gruppen-Anfragen, Ticketshop. Architektur-Skizze, Flow, Verweise auf die Resourcen.

Diese Seite ist die Top-Level-Sicht auf vier Use-Cases, die fast jede Museums-Webseite braucht. Pro Use-Case: Was es ist, welche Architektur sich bewährt hat, welche Schritte du gehst, und wo die konkreten Endpunkte und Beispiele liegen.

Wenn du ins Detail willst, folge den Links in die Resource-Pages.

Voraussetzungen

  • Eure Instanz-URL - Beispiele in der Doku verwenden demo.gomus.de.
  • API-Token - Public-Token reicht für Stammdaten und Verfügbarkeiten. Für Anfragen, Direktbuchungen und Multi-Locale brauchst du einen authentifizierten API-User mit den passenden Permissions. Mehr in Authentifizierung.
  • Cache-Strategie - Stammdaten tageweise, Verfügbarkeiten live. Pflicht. Mehr in Best Practices.

Use-Case 1: Veranstaltungskalender

Worum es geht. Alle öffentlichen Termine eines Museums in einem Kalender oder einer Liste auf eurer Webseite zeigen, jeweils mit Link in den Buchungs-Flow.

Architektur. Der Kalender wird einmal täglich vorgerendert oder serverseitig gecacht; die Webseite serviert HTML/JSON, nicht die go~mus-API direkt. Live-Polling pro Besucher:in ist nicht zulässig.

Flow:

1. Termine holen über GET /api/v4/calendar (aggregierte Tage), GET /api/v4/events (Events mit eingebetteten Dates) oder GET /api/v4/dates (einzelne Termine). Welcher Endpunkt passt, hängt vom Layout ab. Details in Events.

2. Im Frontend rendern - Liste, Tabelle oder Kalender-Widget. Filter nach Museum, Sonderausstellung, Audience, Sprache.

3. Pro Termin verlinken - entweder in den go~mus-Shop (Schema https://<instanz>/#/product/event/<event_id>?date_id=<date_id>) oder, wenn der Termin registerable: true setzt, ein eingebettetes Widget (siehe Widgets).

Mehrsprachig. Wenn DE und EN gleichzeitig gerendert werden sollen, ein Roundtrip statt zwei: Bracket-Form ?locale[]=de&locale[]=en. Setzt API-User-Permission voraus, siehe Multi-Locale.

Stolperdrahte.

  • Termine ohne registerable: true sind reine Anzeige-Termine, kein Buchungslink.
  • Cache-Invalidierung nicht vergessen, sonst zeigst du verschwundene Termine.
  • Default-Datumsbereich ist eng (heute bis Monatsende). Für Vorschau-Kalender start_at und end_at explizit setzen.

Use-Case 2: Direkte Anmeldung für Einzelplätze

Worum es geht. Besucher:innen melden sich auf eurer Webseite für eine öffentliche Führung oder ein Event an, mit oder ohne Bezahlung.

Architektur. Zwei Varianten:

VarianteWannAufwand
Widget einbinden (empfohlen)Schnell live, kein eigener Order-Flowiframe einbetten, fertig
Eigener Flow über die APIVolle Visual-Kontrolle, Customer-Daten in eurem SystemTage bis Wochen

Variante A: Widget. iframe-URL pro Termin (https://<instanz>/widget/event/<event_id>/date/<date_id>). Beispiel-Repo: gomus-public-iframe-example. Mehr in Widgets.

Variante B: API-Flow.

1. Termin-Detail holen über Events: Date-Detail, seats.available prüfen.

2. Optional: Reservation über Reservations, wenn der Checkout länger dauern kann.

3. Order anlegen über Orders mit items: [{ type: "Event", attributes: { id: <date_id>, quantity: N } }].

4. Order finalisieren mit Payment-Info oder als Pay-By-Link, siehe Konzepte: Order Finalize.

Tickets statt Events. Bei klassischen Eintritts-Tickets (Tagesticket, Zeitfenster, Jahreskarte) läuft der Flow analog, mit Ticket-spezifischen Capacity- und Reservation-Endpunkten - siehe Tickets und Annual Tickets.

Stolperdrahte.

  • id im Event-Order-Item ist die Termin-ID (date_id), nicht die Event-ID.
  • Keine Top-Level-Route POST /api/v4/reservations - Reservations leben unter ihrer Resource (tickets/reservations, events/reservations).
  • Order-Erstellung schlägt fehl, wenn deine Preisberechnung von der Server-Berechnung abweicht. Preise immer aus dem Stammdaten-Call ziehen, nicht selbst rechnen. Details in Best Practices.

Use-Case 3: Gruppen-Anfrage

Worum es geht. Eine Schulklasse, eine Reisegruppe, eine Senioren-Gruppe - jemand will eine Führung anfragen, kein direktes Ticket kaufen. Beratungsbedarf, Termin-Abstimmung, manueller Workflow im Backoffice.

Architektur. Webseiten-Formular mit allen Pflichtfeldern, Submit per HTTPS auf eure Server (nicht direkt go~mus, wegen Token-Schutz), eure Server proxen den Call an POST /api/v4/requests.

Flow:

1. Formular auf eurer Webseite mit den nötigen Feldern - Teilnehmerzahl, Wunschtermin, Kontaktdaten, Klassenstufe, Sprache, Anmerkungen.

2. Submit über Requests. Pflichtfelder hängen von eurer Instanz ab.

3. Folgeprozess in go~mus - das Museumsteam sieht die Anfrage im Backoffice, fragt nach, plant das Programm, überführt sie in eine verbindliche Buchung.

Stolperdrahte.

  • Formular-Felder, die Lookup-IDs verlangen (Sprache, Altersgruppe, Klassenstufe, Kategorie), aus den go~mus-Lookups befüllen, nicht hart kodieren.
  • E-Mail-Validierung clientseitig. go~mus prüft auch, aber zu spät für gute UX.
  • Wenn eure Webseite selbst eine Bestätigungsmail schickt, doppelt sich das mit der go~mus-Mail. skip_confirmation_email: true setzen, siehe Requests.

Use-Case 4: Ticketshop

Worum es geht. Besucher:innen kaufen Tickets im Zusammenhang mit eurer Webseite. Die Frage ist nicht ob angebunden wird, sondern wie tief.

Architektur.

VarianteSetupPflegeVisualWann passt das
A: Verlinkung in den go~mus-ShopStundensehr geringBruch beim KlickSchnell live, einfache Ticketstruktur, Marken-Konsistenz nicht kritisch
B: Webcomponents direkt einbettenTage bis WochenmittelnahtlosStarke Marke, Frontend-Ressourcen vorhanden, hohe Conversion-Anforderungen

Verlinkung und Webcomponents schließen sich nicht aus. Hauptseiten als Webcomponents, Newsletter und Drittseiten verlinken in den Standard-Shop - eine verbreitete Kombi.

Variante A. Link-Schema: https://<instanz>/#/product/ticket/<ticket_id> (analog für Events, Tours, Coupons). Sonst nichts zu tun, der Shop wickelt Auswahl, Zahlung, Bestätigung und Mail ab.

Variante B. Custom Elements <go-*> in eure Webseite, voll mit eurem CSS stylebar. Komplette Komponentenliste, Page-Examples für Tickets, Zeitfenster, Warenkorb, Checkout, User-Account in Webcomponents.

Verwandte Seiten