Beschreibung

Worum es geht

Mit Scan-Track übermittelt der GW Server Anwesenheitsänderungen an ein anderes System. Dazu ruft er eine von Ihnen hinterlegte URL auf und übergibt den Ticketcode, den Anwesenheitsstatus und die konfigurierten Gästefelder. Ein solcher automatischer Aufruf wird als Webhook bezeichnet.

Diese Anleitung führt Sie durch die Einrichtung im Portal und beschreibt, wie Ihre technische Betreuung den Empfänger anschließt und prüft.

Voraussetzungen

Die richtige Veranstaltung ist im Portal geöffnet und für die Akkreditierung im GW Server eingerichtet.
Sie können die Akkreditierungseinstellungen der Veranstaltung bearbeiten.
Ein Empfänger steht bereit, der HTTP-POST-Anfragen mit Formulardaten annimmt.
Die Empfänger-URL ist vom Rechner mit dem GW Server erreichbar.
Falls Sie ein Passwort verwenden, ist derselbe Wert am Empfänger hinterlegt.

Verwenden Sie für die Übertragung von Gästedaten und Passwort eine HTTPS-URL.

Scan-Track einrichten

Öffnen Sie in der Veranstaltung Einstellungen → Akkreditierung.
Tragen Sie unter Einstellungen für Scan-Ereignisse im Feld URL für Scan Track&Trace die vollständige Empfänger-URL ein, beispielsweise https://empfaenger.example/scan-track.
Hinterlegen Sie bei Bedarf im Feld Passwort für Scan Track&Trace das mit Ihrer technischen Betreuung vereinbarte Passwort.
Prüfen Sie unter Felder für die Anzeige auf den Akkreditierungs-Geräten die Zuordnung für Titel des Gastes, Vorname des Gastes, Nachname des Gastes, Firma des Gastes und Tag des Gastes. Die dort konfigurierten Inhalte werden auch für Scan-Track verwendet. Nutzen Sie die angebotene Platzhalterauswahl für Ihre veranstaltungsspezifischen Gästefelder.
Klicken Sie auf Speichern.
Stellen Sie vor dem Test sicher, dass der GW Server die aktuellen Veranstaltungseinstellungen übernommen hat.

Das Client Passwort ist eine andere Einstellung: Es dient der Anmeldung der Clients am GW Server. Für den Webhook verwenden Sie Passwort für Scan Track&Trace.

Wenn keine Scan-Track-URL hinterlegt ist, werden für neue Scans keine Scan-Track-Aufträge angelegt.

Wann wird eine Meldung erzeugt?

Entscheidend ist ein erfolgreicher Scan, der die Anwesenheit des Gastes tatsächlich verändert.

Situation	Scan-Track-Meldung
Ein abwesender Gast wird erfolgreich eingecheckt.	Ein Auftrag wird angelegt; bei unverändertem Status wird `present=1` gesendet.
Ein anwesender Gast wird erfolgreich ausgecheckt.	Ein Auftrag wird angelegt; bei unverändertem Status wird `present=0` gesendet.
Ein Scan verändert die Anwesenheit nicht.	Kein neuer Auftrag.
Ein Ticket wird nur zur Information abgefragt.	Kein neuer Auftrag.
Ein Ticket ist unbekannt oder der Scan wird abgewiesen.	Kein neuer Auftrag.
Der GW Server läuft im Demomodus.	Keine Scan-Track-Übertragung.

Ein reiner Wechsel der Gate-Anwesenheit löst keine Meldung aus, solange sich die Anwesenheit des Gastes in der Veranstaltung nicht ändert. Scan-Track ist daher kein vollständiges Protokoll sämtlicher Scans oder Gate-Bewegungen.

So sieht die Anfrage aus

Der GW Server sendet die Anfrage an die konfigurierte URL. Die Übertragung erfolgt als Formulardaten, nicht als JSON.

Bestandteil	Wert
HTTP-Methode	`POST`
Content-Type	`application/x-www-form-urlencoded`
Authentifizierungsheader	`x-gw-auth` mit dem konfigurierten Scan-Track-Passwort; ohne Passwort ist der Wert leer.
Erfolgreiche Antwort des Empfängers	HTTP 200

Das Passwort steht im Header und wird nicht als Formularfeld password übertragen.

Übertragene Felder

Feld	Bedeutung	Beispiel
`present`	Anwesenheit beim jeweiligen Sendeversuch: Zeichenfolge `1` für anwesend, `0` für abwesend.	`1`
`ticketCode`	Ticketcode des Gastes. Als Text verarbeiten, damit beispielsweise führende Nullen erhalten bleiben.	`00123`
`title`	Aufgelöster Inhalt von Titel des Gastes.	`Dr.`
`firstName`	Aufgelöster Inhalt von Vorname des Gastes.	`Erika`
`lastName`	Aufgelöster Inhalt von Nachname des Gastes.	`Musterfrau`
`company`	Aufgelöster Inhalt von Firma des Gastes.	`Beispiel GmbH`
`tag`	Aufgelöster Inhalt von Tag des Gastes.	`VIP`

Die fünf konfigurierbaren Textfelder werden beim auslösenden Scan aus den Veranstaltungsplatzhaltern aufgelöst. Prüfen Sie bei fehlenden Inhalten sowohl die Feldzuordnung als auch die Daten des Testgastes.

Eine Veranstaltungs-ID, Gate-ID, Ereignis-ID und ein Scan-Zeitstempel gehören nicht zu diesen Parametern. Wenn mehrere Veranstaltungen denselben Empfänger nutzen, muss dieser die Veranstaltung anderweitig zuordnen können, beispielsweise über getrennte Empfänger-URLs.

Beispiel: Gast kommt an

Die URL, das Passwort und die Gästedaten in diesem Beispiel sind fiktiv.

POST /scan-track HTTP/1.1
Host: empfaenger.example
Content-Type: application/x-www-form-urlencoded
x-gw-auth: BEISPIELPASSWORT

present=1&ticketCode=00123&title=Dr.&firstName=Erika&lastName=Musterfrau&company=Beispiel+GmbH&tag=VIP

Beim Auschecken wird entsprechend present=0 gesendet, sofern der Gast bis zur Übertragung abwesend bleibt. Der Empfänger muss die Formularcodierung dekodieren; beispielsweise steht + hier für ein Leerzeichen.

Antwort, Wiederholungen und verzögerte Übertragung

Der GW Server verarbeitet vorgemerkte Aufträge im Hintergrund. Der reguläre Prüfzyklus beträgt etwa fünf Sekunden; daraus ergibt sich keine garantierte Zustellzeit. Ohne erkannte Netzwerkverbindung wird die Verarbeitung zunächst verschoben.

HTTP 200: Der Auftrag gilt als erfolgreich und wird entfernt. Der Antwortinhalt wird nicht ausgewertet.
Andere HTTP-Statuscodes: Der Versuch gilt als fehlgeschlagen. Das betrifft auch 201 und 204.
Übertragungsfehler: Eine Ausnahme beim Senden wird intern als -1 erfasst.
Nach drei fehlgeschlagenen Versuchen: Der GW Server protokolliert einen Scan-Track Fehler und entfernt den Auftrag. Es erfolgt keine unbegrenzte automatische Wiederholung.

Der Empfänger sollte HTTP 200 erst nach erfolgreicher Übernahme zurückgeben. Wiederholte Übertragungen müssen ohne unerwünschte doppelte Folgeaktionen verarbeitet werden können, etwa wenn die Verarbeitung bereits abgeschlossen war, die Antwort aber den GW Server nicht erreicht hat.

Wichtig bei verzögerten Meldungen: present wird beim jeweiligen Sendeversuch aus dem aktuellen Gaststatus gelesen. Hat sich die Anwesenheit seit dem auslösenden Scan erneut geändert, kann die Meldung bereits diesen neueren Status enthalten. Die Textfelder stammen dagegen aus dem auslösenden Scan. Verwenden Sie diese Meldungen deshalb nicht als lückenloses, zeitlich exaktes Bewegungsprotokoll.

Verbindung Schritt für Schritt prüfen

Verwenden Sie einen Testgast mit bekanntem Ticketcode und prüfen Sie, dass er zunächst abwesend ist.
Stellen Sie sicher, dass der GW Server nicht im Demomodus läuft und den Empfänger erreichen kann.
Scannen Sie den Gast erfolgreich am Eingang.
Warten Sie, bis der Empfänger die Anfrage erhalten hat. Prüfen Sie ticketCode, present=1, den Header x-gw-auth und die Textfelder.
Kontrollieren Sie, dass der Empfänger HTTP 200 zurückgibt.
Scannen Sie den Gast anschließend erfolgreich am Ausgang und prüfen Sie die nächste Anfrage mit present=0. Die Akkreditierung muss das Auschecken erlauben.
Prüfen Sie ergänzend, dass reine Informationsabfragen und Scans ohne Anwesenheitsänderung keine neuen Meldungen erzeugen.

Warten Sie zwischen Eingang und Ausgang jeweils auf die Übertragung. So prüfen Sie beide Zustände getrennt und vermeiden, dass bereits der nächste Status gesendet wird.

Häufige Fragen und Fehlersuche

Problem	Was Sie prüfen sollten
Es kommt keine Anfrage an.	Richtige Veranstaltung, gespeicherte URL und aktuelle Einstellungen im GW Server prüfen. Anschließend Demomodus, Netzwerkverbindung und tatsächliche Anwesenheitsänderung kontrollieren.
Der Empfänger meldet fehlende Parameter.	Formulardaten aus dem POST-Body lesen; keinen JSON-Body erwarten. Feldnamen einschließlich Groß-/Kleinschreibung beachten, etwa `ticketCode` und `firstName`.
Der Empfänger antwortet mit `401` oder `403`.	Scan-Track-Passwort mit dem empfangenen Header `x-gw-auth` vergleichen. Prüfen, ob ein vorgeschalteter Proxy den Header weitergibt.
Trotz erfolgreicher Verarbeitung kommen Wiederholungen.	Tatsächlichen HTTP-Antwortcode prüfen: Der GW Server erwartet `200`, nicht `201` oder `204`. Auch Verbindungsabbrüche können Wiederholungen verursachen.
Name, Firma oder Tag fehlen.	Platzhalter in Einstellungen → Akkreditierung und die zugehörigen Gästedaten prüfen.
Ein Ausgangsscan erzeugt keine Meldung.	Prüfen, ob der Gast vorher anwesend war, Auschecken erlaubt ist und der Scan erfolgreich war.
Der empfangene Status passt nicht mehr zum ursprünglichen Scan.	Prüfen, ob vor der Zustellung ein weiterer Ein- oder Ausgang erfolgte. Übertragen wird die Anwesenheit beim Sendeversuch.
Im GW Server steht Scan-Track Fehler.	Der Auftrag wurde nach drei Fehlversuchen entfernt. Den protokollierten Statuscode am Empfänger untersuchen; bei `-1` Verbindung, URL und TLS-Konfiguration prüfen.

Kurzübersicht vor dem Einsatz

Empfänger-URL und gegebenenfalls Passwort sind eingerichtet und gespeichert.
Die Einstellungen sind im GW Server angekommen.
Die fünf Gästefelder liefern die gewünschten Inhalte.
Ein- und Ausgang wurden mit einem Testgast getrennt geprüft.
Der Empfänger verarbeitet Formulardaten und antwortet mit HTTP 200.
Wiederholungen und verzögerte Statusmeldungen werden berücksichtigt.

Technischer Abgleich: Portal-Einstellungen und vorliegender GW-Server-Quellstand vom 18.09.2026. Bei abweichenden installierten Serverversionen sollte die technische Betreuung das Verhalten insbesondere für Wiederholungen und Antwortcodes vor dem Einsatz prüfen.