Annual Tickets

Eine Jahreskarte ist ein Ticket vom Typ annual - mehrfach einlösbar, oft personalisiert, manchmal als Geschenk gekauft und später durch die Beschenkten personalisiert. Diese Seite beschreibt den Personalisierungs-Flow nach dem Kauf: wer kann personalisieren, mit welchem Token, und welche Endpoints sind dafür da.

Der Kauf einer Jahreskarte selbst läuft als reguläre Order über POST /api/v4/orders mit einem Ticket vom Typ annual - siehe Tickets und Orders.

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

Mental-Modell

Nach dem Kauf einer Jahreskarte erhält der/die Käufer:in eine Bestätigungsmail mit einem Personalisierungs-Token. Dieser Token öffnet einen eigenen, eingeschränkten Workflow auf dem /annual-Namespace - ohne API-User-Login, nur mit dem Token in der Query.

Order
 └── ticket_sales (n)
      └── personalizations (n)   ← jeder Sitz/jede Karte einzeln
           ├── customer ........ Wer trägt die Karte
           ├── address_id ...... Versandadresse
           └── dispatch_mode_id  Versandart

Eine Jahreskarte kann mehrere Personalisierungen tragen (z.B. Familienkarte). Pro Personalisierung ein eigener Customer.

Endpoints im Überblick

Alle Endpoints unter dem Namespace /api/v4/annual und brauchen ?token=<personalization_token>.

Endpoint	Wofür
`GET /api/v4/annual/order?token=:token`	Order mit allen Ticket-Sales und Personalisierungen abrufen
`POST /api/v4/annual/customers?token=:token`	Neue:n Customer für Personalisierung anlegen (z.B. der/die Beschenkte)
`PUT /api/v4/annual/customers/:id?token=:token`	Customer-Daten ändern
`PUT /api/v4/annual/personalizations/:id?token=:token`	Personalisierung an einen Customer und eine Adresse binden
`POST /api/v4/annual/personalizations/:id/upload?token=:token`	Foto für die personalisierte Karte hochladen
`POST /api/v4/annual/personalization/finalize?token=:token`	Personalisierung abschließen
`PUT /api/v4/annual/ticket_sales/:id?token=:token`	Startdatum (`start_at`) der Karte verschieben

Häufige Aufgaben

Order zur Personalisierung holen

curl "https://demo.gomus.de/api/v4/annual/order?token=PERSONALIZATION_TOKEN"

Antwort enthält:

Customer (der/die Käufer:in)
Adressen
ticket_sales mit personalizations-Array
Pro Personalisierung: aktuelle customer, address_id, dispatch_mode_id und ein Flag ready (Boolean, ob bereit zum Versand)

Neue Person für eine Personalisierung anlegen

Wenn die Jahreskarte verschenkt wird:

curl -X POST "https://demo.gomus.de/api/v4/annual/customers?token=PERSONALIZATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "Peter",
      "surname": "Pan",
      "email": "peter@example.com",
      "customer_salutation_id": 1,
      "addr_city": "Berlin",
      "addr_country_id": 60,
      "addr_street": "Brunnenstraße 7D",
      "addr_zip": "10119"
    }
  }'

Antwort enthält neuen customer.id, eine addresses[]-Liste sowie - wichtig - einen personalization_token. Diesen brauchst du im nächsten Schritt.

Personalisierung an Customer binden

curl -X PUT "https://demo.gomus.de/api/v4/annual/personalizations/:id?token=PERSONALIZATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "personalization": {
      "customer_personalization_token": "13fe3a0d-...",
      "customer_adress_id": 151,
      "dispatch_mode_id": 3
    }
  }'

customer_personalization_token kommt aus dem Customer-Create-Response. customer_adress_id ist die Versandadresse. dispatch_mode_id aus den Lookups.

Startdatum der Karte ändern

curl -X PUT "https://demo.gomus.de/api/v4/annual/ticket_sales/:id?token=PERSONALIZATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ticket_sale": { "start_at": "2026-06-01 10:00:00" } }'

Stolperdrahte

Token-basiert, nicht User-basiert. Der /annual-Namespace funktioniert ohne API-User-Login - der Personalisierungs-Token aus der Bestellbestätigungs-Mail ist die Auth. Entsprechend: Token niemals in URL-Logs oder Frontend-Routern als Query-String belassen, lieber serverseitig durchreichen.
Zwei verschiedene Tokens. Es gibt den Personalisierungs-Token der Order (öffnet den Flow) und den customer_personalization_token (identifiziert ein neu angelegtes Customer-Subjekt für die Personalisierungs-Bindung). Nicht verwechseln.
Adress-Feld heißt customer_adress_id (mit einem d) im Personalization-Update. Schreibfehler im Server-Schema, lebt seit Jahren so.
dispatch_mode_id aus Lookups holen. IDs sind instanz-spezifisch - siehe Lookups.