Konzepte

Die Vokabeln der go~mus-API in einem Sprung erklärt - Instance, Mandantentrennung, Stammdaten vs. Live-Daten, Tokens, Quotas, Reservations, Orders.

Diese Seite definiert die Begriffe, die du in den Szenarien und in der Referenz wiederfindest. Lies sie einmal komplett, danach blätterst du nur noch zurück.

Instance

go~mus ist eine Web-App, die in der Cloud betrieben wird. Jede Kundin betreibt eine oder mehrere Instanzen (auch „Hosts“). Eine Instanz hat eine eigene URL, meist als Sub-Domain unter gomus.de, in einigen Ländern auch unter gomus.at, gomus.ch, gomus.be oder gomus.lu.

Die Datenbestände der Instanzen sind physisch und logisch getrennt. Du sprichst immer mit einer konkreten Instanz, nie übergreifend.

Beispiele:

  • Ein Museum: stiftung-a.gomus.de
  • Ein Verbund mit drei Häusern: stiftung-b.gomus.de
  • Ein Verbund, der zwei Standorte trennt: stiftung-c-berlin.gomus.de und stiftung-c-hamburg.gomus.de

Die API ist pro Instanz unter /api/v4 erreichbar.

Museum

Innerhalb einer Instanz gibt es eines oder mehrere Museen. Tickets, Tours, Events sind Museen zugeordnet. Tokens können auf bestimmte Museen einer Instanz beschränkt sein.

Locale / Mehrsprachigkeit

Inhalte können in mehreren Sprachen geliefert werden. Die unterstützten Sprachen werden auf Instanz-Ebene konfiguriert. Per Query-Parameter locale rufst du eine Sprache oder mehrere gleichzeitig ab. Beispiel: ?locale=de.

Stammdaten vs. Live-Daten

Zwei Datenkategorien mit unterschiedlicher Update-Frequenz:

  • Stammdaten: Beschreibungen, Titel, Bilder, Preise (außer Dynamic Pricing). Ändern sich selten. Tageweise oder einmal je Saison cachen.
  • Live-Daten: Verfügbarkeiten, freie Plätze, Kontingente, Start-Zeiten. Direkt vor der Buchung oder Anzeige live abfragen, sinnvoll cachen (kurze TTL).

Direkt-Live-Traffic auf Stammdaten vermeiden. Cache-Strategie ist Pflicht.

Public API vs. Reseller API

Die API hat zwei Bereiche:

  • Public: lesend. Zugänglich für nicht-authentifizierte Aufrufe. Manche Endpunkte verlangen Auth.
  • Reseller: lesend und schreibend. Für Vertriebspartner und Buchungsplattformen. Reseller-Tokens haben Rate-Limits.

Beide Bereiche sind in der OpenAPI-Spec dokumentiert.

Tokens und Kontextsensitivität

go~mus-Tokens sind kontextsensitiv. Heißt: Der gleiche Endpoint liefert je nach Token unterschiedliche Daten oder Felder. Beispiel: Ein Reseller-A-Token sieht nur die Tickets, die für Reseller A freigegeben sind. Ein User-Token sieht das Backend-Inventar.

Daraus folgt:

  • Tokens nicht teilen. Jeder externe Partner hat einen eigenen.
  • Tokens nie clientseitig auslagern (z.B. nicht in Browser-JS einbetten). Server-seitig halten und proxen.
  • Tokens via Authorization: Bearer <token> in jedem Request mitgeben.

Limited Resources: Quotas, Capacities, Seats

Tickets, Tours und Events sind grundsätzlich limitiert. Die Mechanik unterscheidet sich pro Produkttyp:

  • Quota: gemeinsamer Pool von Plätzen, an dem ein oder mehrere Tickets hängen. Eine Buchung gelingt nur, wenn in allen beteiligten Quotas Platz ist.
  • Tickets: dedizierte Endpunkte GET /api/v4/tickets/:id/capacity?date=YYYY-MM-DD und GET /api/v4/tickets/capacities für mehrere Tickets gleichzeitig. Die Antwort listet Zeitfenster und buchbare Mengen.
  • Events: keine separate Capacity-Route. Die Belegung steht direkt im Termin-Detail unter seats.available (zusätzlich seats.min, seats.max, seats.booked). Endpunkt: GET /api/v4/events/:event_id/dates/:id.
  • Tours: Verfügbarkeit über Start-Times. GET /api/v4/tours/:id/start_times bzw. GET /api/v4/tours/:id/start_times/:date.
  • Saalplan-Events: zusätzlich Sitzplatz-spezifische Belegung im Termin-Detail über seatings.

Vor jeder Buchung den passenden Verfügbarkeits-Call ausführen, sonst handelst du im Blindflug.

Reservation

Eine kurzfristige Sperre für ein Ticket ohne fixe Order. Hält den Platz für 5 Minuten, max. 60 Minuten verlängerbar, damit du den Buchungsprozess in Ruhe abschließen kannst.

  • Endpunkt: POST /api/v4/tickets/reservations mit Payload { "reservation": { "ticket_id", "quantity", "start_at" } }
  • Antwort enthält ein token, das in der Order unter attributes.reservations: [<token>] eingelöst wird.
  • Update / Refresh: PUT /api/v4/tickets/reservations/:token
  • Kombinations-Tickets können nicht reserviert werden.

Stand: Tickets sind produktiv. Für Events existiert eine Reservations-Mechanik (POST /api/v4/events/reservations), die aktuell noch in Arbeit ist und derzeit nur für öffentliche Tour-Bookings funktioniert - geplant ist die volle Abdeckung wie bei Tickets. Tours haben keine eigene Reservations-Route; dort wird der Verfügbarkeitskonflikt in der Anfrage- bzw. Order-Bearbeitung aufgelöst.

Empfohlener Ticket-Flow: Capacity-Check → Reservation → Order erstellen und Reservation einlösen.

Empfohlener Event/Tour-Flow heute: Termin-/Start-Time-Detail prüfen → Order erstellen.

Order und Order Item

Eine Order ist die fertige Buchung. Du enthält ein oder mehrere Order Items (einzelne Produkte: Ticket X, Event Y, Tour Z, Spende, Wertgutschein).

Beim Erstellen schickst du den von dir berechneten Preis mit. Der Server prüft gegen seine eigene Berechnung. Wenn die Werte abweichen, lehnt der Server ab. Diese Sicherheits-Mechanik schützt vor Preismanipulation und falsch konfigurierten Rabatten.

Order Finalize

Eine Order anzulegen reicht oft nicht. Mit POST /api/v4/orders/:id/finalize reicherst du sie an mit Kunden-, Adress-, Zahlungsinfos und schließt sie ab. Erst nach Finalize wird die Bestellbestätigung verschickt und das Ticket gültig.

Sonderfall des Finalize: Order wird angelegt und finalisiert, aber als „pay_by_link“ markiert. Der Kunde bekommt einen Zahllink per Mail. Wenn nach X Minuten keine Zahlung erfolgt, automatischer Storno. Sinnvoll, wenn dein System keine integrierte Bezahlung hat oder der Kunde später bezahlen soll.

Customers und foreign_id

Customers sind Personen, die Bestellungen ausgelöst haben. Wenn du ein eigenes CRM hast, hänge eine foreign_id (deine ID) an den Customer. Beim nächsten Zugriff identifizierst du dann via foreign_id statt go~mus-ID. Vorteil: kein Mapping-Tabellen-Pflegen auf deiner Seite.

Die foreign_id sollte möglichst eindeutig sein (z.B. 16 Zufallszeichen oder eine UUID).

Institutions

Auch wenn Orders immer von einer Person ausgelöst werden, kannst du Institutionen (Schule, Verein, Firma) abbilden. Über addr_institution im Customer-Payload. Die Order ist dann der Institution zugeordnet und wird bei hinterlegtem Rabatt entsprechend reduziert.

Requests / Anfragen

Anfragen sind unverbindliche Vorstufen zu Buchungen. Typisch bei Gruppenanfragen, wo Beratung vor Buchung nötig ist. POST /api/v4/requests legt eine Anfrage an. Der Folgeprozess (Beratung, Programmplanung, verbindliche Buchung) läuft im go~mus-Backend.

Tickets, Tours, Events

Drei zentrale Produkttypen:

  • Tickets: Eintritt, Tageskarte, Zeitfenster, Familienkarte, Jahreskarte.
  • Tours: Gruppen-Führungen mit Beratungsbedarf, Programmplanung.
  • Events: Einzelplatz-Veranstaltungen mit Terminen, oft mit Kapazitäts-Limit.

Die ID eines Produkts ist eindeutig in Kombination aus Instanz und Produkttyp. Heißt: Ticket 3 auf demo.gomus.de ist nicht das gleiche wie Ticket 3 auf andere.gomus.de.

Seating Maps

Events können einen Saalplan haben, mit Reihen, Sitzen und Preiskategorien. Über die API kannst du den Saalplan abfragen, freie Sitze sehen und konkrete Sitze buchen. Empfohlen: Workshop, weil das Modell etwas tiefer ist.

Bar- und QR-Codes

Jedes Ticket hat einen eindeutigen Code, der als 1D- oder 2D-Code (QR empfohlen) gedruckt wird. Bei Einzelbesuch passt ein Ticket = ein Code. Gruppen-Tickets können mit nur einem Code für die ganze Gruppe ausgegeben werden.

Datenaktualität: Pull statt Push

go~mus liefert aktuell keine Webhooks für Datenänderungen. Heißt: kein Push aus go~mus zu eurem System bei Updates an Stammdaten, Kontingenten oder Bestellungen.

Empfohlene Strategie:

  • Stammdaten (Tickets, Events, Tours, Beschreibungen, Bilder): einmal pro Tag paginiert pollen und cachen.
  • Verfügbarkeiten und Kapazitäten: live abfragen, direkt vor der Anzeige oder Buchung. Sinnvoll cachen mit kurzer TTL.
  • Bestellungen und Anfragen: werden in den Responses übermittelt und können für einen begrenzten Zeitraum nach Erstellung live abgefragt werden.

Eine ausgereifte Pull- und Caching-Strategie ist Pflicht für produktive Integrationen. Direkter Live-Traffic auf Stammdaten ohne Cache wird abgelehnt und bringt deine Integration nicht in Produktion.