Requests

Der Requests-Endpunkt ist die Brücke vom öffentlichen Anfrage-Formular auf eurer Webseite in die go~mus-Anfragen-Bearbeitung. Schulklassen, die eine Führung anfragen, Reisegruppen mit Wunschtermin, Seniorengruppen mit besonderen Bedürfnissen - alles, was im Backoffice manuell beraten und bestätigt wird, beginnt typischerweise hier.

Im Gegensatz zu Tickets, Events und Tours ist Requests kein Verkaufs-Endpunkt. Eine Anfrage ist keine Buchung - sie löst einen menschlichen Workflow aus.

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

Endpoints im Überblick

Endpoint	Aktion	Auth
`POST /api/v4/requests`	Anfrage erstellen	API-User mit Schreibrechten auf Anfragen

Es gibt keinen GET-/PUT-/DELETE-Endpunkt für Requests. Anfragen werden nur erstellt; alles weitere passiert im go~mus-Backoffice.

Lifecycle

   Webseiten-Formular
        │
        ▼
   POST /api/v4/requests
        │
        ▼
  ┌────────────┐
  │  pending   │ ─── Customer angelegt/verlinkt, Adresse zugeordnet
  └─────┬──────┘
        │
        ▼
  ┌────────────┐
  │ registered │ ─── Bestätigungsmail an Customer (außer bei skip_confirmation_email)
  └─────┬──────┘
        │
        ▼
   manuell im Backoffice: bestätigen, anpassen, in Buchung überführen, ablehnen

Anatomie einer Request

Top-Level-Felder:

participants (integer) - Teilnehmerzahl
companions (integer) - Begleitpersonen (Lehrer:innen, Aufsicht)
date (YYYY-MM-DD) - Wunschtermin (model-validierungsmäßig Pflicht)
notes (string) - Freitext-Bemerkungen, besondere Wünsche
payment_mode (id oder Name) - Zahlungsweise (z.B. "Rechnung", "Bar")
language (id oder Name) - bevorzugte Sprache der Führung
age_group (id oder Name) - Altersgruppe
grade (id oder Name) - Klassenstufe
proposal_category (id oder Name) - Vorschlagskategorie
category (id oder Name) - Kunden-Kategorie / Price Target Audience (z.B. "Schule")
skip_confirmation_email (boolean, Default false) - Bestätigungsmail unterdrücken
items (Array, Pflicht, mindestens ein Eintrag) - angefragte Tours
customer (Object, optional) - Customer-Daten

Eintrag im items-Array:

tour_id (integer, Pflicht) - Produkt-ID der angefragten Tour
time (HH:MM) - Wunsch-Startzeit

Customer-Object:

name, surname, email, phone, mobile
salutation, title - per Name oder ID, siehe Lookups
street, zip, city, state, country
category, language - per Name oder ID

Häufige Aufgaben

Anfrage anlegen

curl -X POST "https://demo.gomus.de/api/v4/requests" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "participants": 15,
      "companions": 2,
      "date": "2026-09-15",
      "notes": "Wir brauchen rollstuhlgerechten Zugang.",
      "payment_mode": "Rechnung",
      "language": "Deutsch",
      "age_group": 1,
      "grade": 3,
      "category": "Schule",
      "items": [
        { "tour_id": 42, "time": "14:00" }
      ],
      "customer": {
        "name": "Max",
        "surname": "Mustermann",
        "email": "max@example.com",
        "salutation": "Herr",
        "phone": "+49 30 12345678",
        "street": "Musterstraße 123",
        "zip": "10115",
        "city": "Berlin",
        "country": "Deutschland"
      }
    }
  }'

Erfolgs-Response (200):

{
  "request": {
    "id": 123,
    "created_at": "2026-09-01T10:30:00+02:00",
    "updated_at": "2026-09-01T10:30:00+02:00"
  }
}

Bestätigungsmail unterdrücken

Wenn eure Webseite bereits eine eigene Bestätigungsmail nach Formular-Absenden verschickt, würde die go~mus-Mail doppeln. skip_confirmation_email: true setzen:

{
  "request": {
    "skip_confirmation_email": true,
    "...": "..."
  }
}

Default ist false (Mail wird verschickt).

Lookup-Felder: id oder Name

Mehrere Felder akzeptieren entweder eine numerische ID oder den übersetzten Namen als String:

payment_mode, language, age_group, grade, proposal_category, category
Customer-Felder: salutation, title, country, state, category, language

Der Server probiert erst die ID, fällt auf den Namen-Lookup zurück. Praktisch, wenn das Webseiten-Formular freie Text-Inputs hat oder Dropdown-Werte aus den Lookups zieht.

Stolperdrahte

API-User mit Schreibrechten auf Anfragen Pflicht. Public-Token funktioniert nicht, der Endpunkt wird in der Praxis serverseitig durchgereicht. Vor Live-Gang die Schreibberechtigung auf eurem API-User freischalten lassen, sonst kommt 401. Sprich uns dazu an.
items darf nicht leer sein. Mindestens ein { tour_id, time }-Eintrag, sonst 422.
date ist Pflicht. Fehlt das Besuchsdatum, lehnt der Server die Anfrage mit 422 ab.
Lookup-Werte sind instanz-spezifisch. Sprache "Deutsch", Kategorie "Schule", Altersgruppe-IDs - alles aus den Lookups holen, nicht hart kodieren.
Kein Lookup nach Create. Es gibt keinen GET-Endpunkt für Requests. Wer den Status der Anfrage später wissen will, braucht das go~mus-Backoffice oder ein eigenes State-Tracking auf Webseiten-Seite.
Customer-Verknüpfung passiert serverseitig. Wenn die email einem bestehenden Customer entspricht (oder per foreign_id gefunden wird), hängt die Request am bestehenden Datensatz. Sonst legt der Server einen neuen Customer an. Das bedeutet auch: Eingaben auf eurer Webseite müssen DSGVO-konform erfasst und übertragen werden.