Disco-Drehkreuz (Turnstile-API)¶

Die Drehkreuz-API entscheidet an einem Karten-Einbehalt-Drehkreuz, ob eine Disco-Gastkarte den Veranstaltungsort verlassen darf. Sie ist bewusst einfach gehalten, damit ein Drehkreuz-Controller sie ohne Anmeldung (JWT) aufrufen kann: der API-Key wird in der URL übergeben.

Einrichtung¶

Admin → Disco → Allgemein → Drehkreuz (Turnstile-API)

„Generieren" erzeugt einen API-Key (wird vollständig angezeigt).
Speichern.
Die Anbindungs-URL daneben mit „Kopieren" übernehmen und im Drehkreuz hinterlegen.

Ein leerer API-Key deaktiviert die Drehkreuz-API.

Aufruf¶

GET /api/v1/disco/turnstile/{key}/{kartenId}
POST /api/v1/disco/turnstile/{key}/{kartenId}

{key} — der konfigurierte API-Key.
{kartenId} — die ID der aufgelegten Gastkarte.

Die Antwort ist ein JSON-Objekt:

{ "canExit": true, "message": "Karte kann raus — Restguthaben 5,00 €", "refund": 5.0, "status": "ok" }

message ist für die Anzeige am Drehkreuz gedacht.

Statuscodes¶

Code	Bedeutung	Drehkreuz
200	Karte ist gedeckt — darf raus (`refund` = evtl. Restguthaben)	öffnen
402	Es ist noch ein Betrag offen — bitte zur Kasse	gesperrt
423	Karte ist gesperrt	gesperrt
409	Karte ist bereits abgerechnet	gesperrt
404	Karte unbekannt	gesperrt
401	API-Key fehlt oder ist falsch	gesperrt

Regel am Kreuz: 200 = öffnen, alles andere = gesperrt und message anzeigen.

Abrechnung & Lizenz-Seat¶

Bei einer gedeckten Karte (Status 200) rechnet das Drehkreuz die Karte sofort ab — unter einem eigenen, automatisch angelegten Benutzer „Drehkreuz". Dabei meldet sich das Drehkreuz wie ein Kassengerät an und belegt damit einen Lizenz-Seat.

Kann die Karte ausnahmsweise nicht sofort abgerechnet werden (z. B. weil kein Seat frei ist), darf der Gast trotzdem hinaus — die Karte wird dann beim Tagesabschluss abgerechnet.

Restguthaben

Ein verbleibendes Kartenguthaben (refund) wird am Drehkreuz nicht ausgezahlt. Der Gast holt es an der Kasse ab; die Verbuchung folgt der Einstellung Restguthaben auf Karten (Auszahlen / Guthaben-Verfall / Trinkgeld).