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 weist den Aufrufer aus.

Einrichtung¶

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

„Generieren" erzeugt einen API-Key (wird vollständig angezeigt).
Speichern.
Den Schlüssel im Drehkreuz hinterlegen. Die Anbindungs-URL daneben („Kopieren") enthält den Schlüssel bereits — sie passt zum unten beschriebenen älteren Aufruf über den Pfad.

Ein leerer API-Key deaktiviert die Drehkreuz-API.

Aufruf (empfohlen: Schlüssel in der Kopfzeile)¶

GET  /api/v1/disco/turnstile/{kartenId}
POST /api/v1/disco/turnstile/{kartenId}
X-Dikas-Turnstile-Key: {key}

{kartenId} — die ID der aufgelegten Gastkarte.
X-Dikas-Turnstile-Key — der konfigurierte API-Key.

Warum die Kopfzeile die bessere Anbindung ist

Ein Schlüssel im Adresspfad steht in jedem Zugriffsprotokoll — im Proxy, im Webserver und in jeder Zwischenstation. In der Kopfzeile taucht er dort nicht auf. Richten Sie ein neues Drehkreuz ein, nehmen Sie deshalb diesen Weg.

Aufruf über den Pfad (älterer Weg, funktioniert weiter)¶

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

Fachlich identisch — vorhandene Drehkreuze und Steuerungen, die sich nicht auf Zuruf umstellen lassen, laufen unverändert weiter. Schickt ein Gerät beides, gilt der Schlüssel aus der Kopfzeile.

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).