Ticket-API für Webshops
Über die Ticket-API kann ein Webshop Eintrittstickets anlegen, abfragen, ändern und sperren. Angelegte Tickets sind sofort an der Zutrittskontrolle gültig. Den Scancode, der auf das Ticket gedruckt wird, vergibt der Server.
Verkauf, Zahlung und Rechnungsstellung bleiben vollständig im Webshop.
Zugangsdaten
Vom Betreiber erhalten Sie:
- die Adresse des Servers (Hostname und Port)
- einen Token für den Zugriff
- die Artikelnummern der Tickets, die über den Webshop verkauft werden dürfen
Für jeden Ticketartikel sind beim Betreiber Vorgaben hinterlegt (Zone, Dauer, Ticketart usw.). Diese werden automatisch übernommen und können je Ticket überschrieben werden.
Grundlagen
Adresse
https://<server>:<port>/TICKET/Ticket
Die Verbindung erfolgt ausschließlich über HTTPS.
Authentifizierung
Jeder Aufruf benötigt den Token im HTTP-Header token:
token: <Ihr Token>
Der Token darf nur serverseitig im Webshop verwendet werden und nie im Browser des Kunden landen.
Request
- Request-Body im Format JSON, Zeichensatz UTF-8 (
Content-Type: application/json) - Datumswerte nach ISO 8601 ohne Zeitzone:
YYYY-MM-DDThh:mm:ss. Es gilt die Ortszeit des Betreibers.
Response
Jede Antwort hat denselben Aufbau. Der Status steht sowohl im HTTP-Statuscode als auch in status.
data ist nur bei Erfolg (Status 2xx) enthalten.
{
"status": { "code": 200, "text": "Ok" },
"meta": { "function": "TICKET/Ticket/2026292123454", "mandant": 1, "version": "5.3.010.037" },
"data": { ... }
}
meta dient nur der Information und kann ignoriert werden.
Statuscodes
| Code | Bedeutung |
|---|---|
| 200 | Erfolgreich |
| 201 | Tickets wurden angelegt |
| 400 | Ungültige Anfrage, z.B. fehlende Felder oder unbekannte Artikelnummer. Der Grund steht in status.text. |
| 401 | Token fehlt oder ist ungültig |
| 403 | Token ist für diese Funktion nicht berechtigt |
| 404 | Ticket bzw. Referenz nicht gefunden |
| 405 | HTTP-Methode für diesen Pfad nicht erlaubt |
| 409 | Ticket wurde bereits benutzt bzw. ist gesperrt und kann nicht geändert werden |
| 500 | Interner Serverfehler. Bitte wenden Sie sich an den Betreiber. |
Ticket-Objekt
Alle Funktionen liefern Tickets in folgender Form:
{
"Scancode": "2026292123454",
"Artikelnummer": "100123",
"XXAK": "",
"XYAK": "",
"Bezeichnung": "Tageskarte",
"Zutrittszone": "A",
"GueltigAb": "2026-11-01T10:00:00",
"Zutrittsdauer": 120,
"Funktion": 0,
"APB": true,
"Ermaessigt": false,
"Nachzahlkontrolle": false,
"TicketStatus": 0,
"TicketStatusText": "unbenutzt",
"Zutritt": null,
"Ausgang": null,
"Referenz": "WS-4711",
"Position": "1"
}
| Feld | Typ | Beschreibung |
|---|---|---|
| Scancode | Text (13) | EAN-13-Code des Tickets, wird vom Server vergeben und auf das Ticket gedruckt |
| Artikelnummer | Text | Ticketartikel |
| XXAK, XYAK | Text (max. 20) | Variante des Artikels (optional, nur nach Absprache mit dem Betreiber) |
| Bezeichnung | Text | Bezeichnung des Artikels (nur lesend) |
| Zutrittszone | Text (max. 10) | Zonen, für die das Ticket gilt, z.B. A oder AB. Erlaubt sind A–Z und ! (alle Zonen). |
| GueltigAb | Datum oder null | Beginn der Gültigkeit. Bei null beginnt die Zutrittsdauer mit dem ersten Eintritt. |
| Zutrittsdauer | Zahl | Erlaubte Aufenthaltsdauer in Minuten |
| Funktion | Zahl | Ticketart, siehe unten |
| APB | Boolean | Anti-Pass-Back-Kennzeichen |
| Ermaessigt | Boolean | Ermäßigtes Ticket |
| Nachzahlkontrolle | Boolean | Bei Überschreitung der Zutrittsdauer ist eine Nachzahlung erforderlich |
| TicketStatus | Zahl | Aktueller Status an der Zutrittskontrolle, siehe unten (nur lesend) |
| TicketStatusText | Text | Bezeichnung des Status (nur lesend) |
| Zutritt | Datum oder null | Zeitpunkt des Eintritts (nur lesend) |
| Ausgang | Datum oder null | Zeitpunkt des Austritts (nur lesend) |
| Referenz | Text (max. 40) | Bestellnummer des Webshops |
| Position | Text (max. 20) | Positionsreferenz des Webshops (optional) |
Die Vorgaben für Zone, Dauer, Ticketart, APB, Ermäßigung und Nachzahlkontrolle legt der Betreiber je Artikel fest. Überschreiben Sie diese Werte nur nach Absprache.
Funktion (Ticketart)
| Wert | Bedeutung |
|---|---|
| 0 | Einzelkarte |
| 1 | Mehrfachkarte |
| 2 | Saisonkarte |
| 3 | Ausgangskarte |
| 4–8 | weitere Ticketarten nach Absprache mit dem Betreiber |
TicketStatus
| Wert | Bedeutung |
|---|---|
| 0 | unbenutzt |
| 5 | Ersatzticket erforderlich |
| 6 | gesperrt |
| 10 | Warten auf Eingang |
| 20 | Eingang erfolgt |
| 30 | Zeitüberschreitung |
| 40 | Warten auf Ausgang |
| 100 | Ausgang erfolgt |
| 110 | manuell abgemeldet |
Ab Status 10 gilt ein Ticket als benutzt. Werten Sie im Webshop bitte TicketStatus aus;
TicketStatusText ist nur ein Anzeigetext und kann sich ändern.
Funktionen
| Methode | Pfad | Funktion |
|---|---|---|
| GET | /TICKET/Ticket/{Scancode} | Ticket abfragen |
| GET | /TICKET/Ticket?Referenz={Referenz} | Alle Tickets einer Bestellung abfragen |
| POST | /TICKET/Ticket | Tickets einer Bestellung anlegen |
| PUT | /TICKET/Ticket/{Scancode} | Ticket ändern |
| DELETE | /TICKET/Ticket/{Scancode} | Ticket sperren |
| DELETE | /TICKET/Ticket?Referenz={Referenz} | Alle Tickets einer Bestellung sperren |
Über die API sind nur Tickets erreichbar, die auch über die API angelegt wurden.
Tickets anlegen
POST /TICKET/Ticket
Legt alle Tickets einer Webshop-Bestellung in einem Schritt an.
Request
{
"Referenz": "WS-4711",
"Tickets": [
{
"Artikelnummer": "100123",
"Anzahl": 2,
"Position": "1",
"GueltigAb": "2026-11-01T10:00:00"
},
{
"Artikelnummer": "100124",
"Position": "2"
}
]
}
| Feld | Pflicht | Beschreibung |
|---|---|---|
| Referenz | ja | Bestellnummer des Webshops, max. 40 Zeichen, je Bestellung eindeutig |
| Tickets | ja | Liste der Positionen, mindestens eine |
| Tickets[].Artikelnummer | ja | Ticketartikel |
| Tickets[].Anzahl | nein | Anzahl Tickets dieser Position (Standard 1). Jedes Ticket erhält einen eigenen Scancode. |
| Tickets[].Position | nein | Positionsreferenz des Webshops |
| Tickets[].GueltigAb, Zutrittszone, Zutrittsdauer, Funktion, APB, Ermaessigt, Nachzahlkontrolle, XXAK, XYAK | nein | Überschreiben die Vorgaben des Artikels |
Je Aufruf sind maximal 500 Tickets erlaubt.
Response – 201 Tickets angelegt, data enthält die Liste aller Tickets der Bestellung.
{
"status": { "code": 201, "text": "Tickets angelegt" },
"meta": { "function": "TICKET/Ticket", "mandant": 1, "version": "5.3.010.037" },
"data": [
{ "Scancode": "2026292123454", "Artikelnummer": "100123", "Position": "1", "TicketStatus": 0, "...": "..." },
{ "Scancode": "2026292123461", "Artikelnummer": "100123", "Position": "1", "TicketStatus": 0, "...": "..." },
{ "Scancode": "2026292123478", "Artikelnummer": "100124", "Position": "2", "TicketStatus": 0, "...": "..." }
]
}
Verhalten
- Die Bestellung wird vollständig oder gar nicht angelegt. Ist eine Position fehlerhaft, kommt
400mit Angabe der Position, z.B.Ticket 2: Artikel 100124 ist kein Ticketartikel. - Wiederholung: Gibt es zur Referenz bereits Tickets, werden keine neuen angelegt. Die vorhandenen Tickets
werden unverändert mit
200 Tickets zur Referenz bereits vorhandenzurückgegeben. Ein Aufruf kann daher nach einem Verbindungsabbruch gefahrlos wiederholt werden. - Weitere Tickets zu einer bereits übertragenen Bestellung benötigen eine neue Referenz (z.B.
WS-4711-2).
Ticket abfragen
GET /TICKET/Ticket/{Scancode}
GET /TICKET/Ticket?Referenz={Referenz}
Mit Scancode enthält data ein Ticket-Objekt, mit Referenz eine Liste aller Tickets der Bestellung.
Wird nichts gefunden, kommt 404.
{
"status": { "code": 200, "text": "Ok" },
"meta": { "function": "TICKET/Ticket/2026292123454", "mandant": 1, "version": "5.3.010.037" },
"data": { "Scancode": "2026292123454", "TicketStatus": 20, "TicketStatusText": "Eingang", "Zutritt": "2026-11-01T10:12:31", "...": "..." }
}
Ticket ändern
PUT /TICKET/Ticket/{Scancode}
Ändert ein unbenutztes Ticket. Es müssen nur die zu ändernden Felder übergeben werden.
Request
{
"GueltigAb": "2026-11-02T10:00:00"
}
Änderbar sind Artikelnummer, XXAK, XYAK, Position, Zutrittszone, GueltigAb, Zutrittsdauer,
Funktion, APB, Ermaessigt und Nachzahlkontrolle. Scancode und Referenz bleiben unverändert.
Wird eine andere Artikelnummer übergeben, gelten zunächst die Vorgaben des neuen Artikels; die übrigen Felder aus dem Request werden danach angewendet.
Response – 200, data enthält das geänderte Ticket.
Bereits benutzte oder gesperrte Tickets liefern 409.
Ticket sperren
DELETE /TICKET/Ticket/{Scancode}
DELETE /TICKET/Ticket?Referenz={Referenz}
Sperrt ein Ticket bzw. alle Tickets einer Bestellung, z.B. bei Storno. Gesperrte Tickets werden an der Zutrittskontrolle abgewiesen und bleiben abrufbar (TicketStatus 6).
- Gesperrt werden können nur unbenutzte Tickets.
- Ist bei einer Referenz auch nur ein Ticket bereits benutzt, kommt
409und es wird kein Ticket gesperrt. - Ein erneuter Aufruf für bereits gesperrte Tickets liefert wieder
200.
Response – 200, data enthält das gesperrte Ticket bzw. die Liste der Tickets.
Beispiele mit curl
# Tickets anlegen
curl -X POST "https://<server>:<port>/TICKET/Ticket" \
-H "token: <TOKEN>" -H "Content-Type: application/json" \
-d '{"Referenz":"WS-4711","Tickets":[{"Artikelnummer":"100123","Anzahl":2}]}'
# Tickets einer Bestellung abfragen
curl "https://<server>:<port>/TICKET/Ticket?Referenz=WS-4711" -H "token: <TOKEN>"
# Ticket ändern
curl -X PUT "https://<server>:<port>/TICKET/Ticket/2026292123454" \
-H "token: <TOKEN>" -H "Content-Type: application/json" \
-d '{"GueltigAb":"2026-11-02T10:00:00"}'
# Bestellung stornieren
curl -X DELETE "https://<server>:<port>/TICKET/Ticket?Referenz=WS-4711" -H "token: <TOKEN>"