Beschreibung

Worum es geht

BeiMit Scan-Track übermittelt der Scan-TrackGW SchnittstelleServer handeltAnwesenheitsänderungen esan sichein umanderes einenSystem. Webhook,Dazu welcherruft beimer Eingangs-eine von Ihnen hinterlegte URL auf und Ausgangsscanübergibt aufgerufenden werdenTicketcode, kann.den DerAnwesenheitsstatus URLund hierfürdie konfigurierten Gästefelder. Ein solcher automatischer Aufruf wird inals Webhook bezeichnet.

Diese Anleitung führt Sie durch die Einrichtung im Portal und beschreibt, wie Ihre technische Betreuung den EinstellungEmpfä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 hinterlegt.bearbeiten. ZumEin Empfänger steht bereit, der HTTP-POST-Anfragen mit Formulardaten annimmt. Die Empfänger-URL kannist auchvom nochRechner mit dem GW Server erreichbar. Falls Sie ein Passwort gesetztverwenden, werden.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.

WirWenn 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 amwird Eingang,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 einder anbwesender Gast am Ausgang gescannt, soScan wird abgewiesen. Kein neuer Auftrag. Der GW Server läuft im Demomodus. Keine Scan-Track-Übertragung.

Ein reiner Wechsel der URLGate-Anwesenheit mitlö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 Parametern ( Content-Type application/x-www-form-urlencoded)urlencoded aufgerufen. 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 wirdsteht im Header 'x-gw-auth'und übergeben.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 Parameterfünf umfassen: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.

• present:HTTP Gibt200: AufschlussDer darüber,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 nunvorher anwesend oderwar, abwesendAuschecken erlaubt ist ('0'und |der '1')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. ticketCode:Wiederholungen Derund Ticketcodeverzögerte desStatusmeldungen Gasteswerden title: Der Inhalt des Feldes Titel, so wie er in den Veranstaltungs-Einstellungen definiert wurde. firstName: Der Inhalt des Feldes Vorname, so wie er in den Veranstaltungs-Einstellungen definiert wurde. lastName: Der Inhalt des Feldes Nachname, so wie er in den Veranstaltungs-Einstellungen definiert wurde. company: Der Inhalt des Feldes Firma, so wie er in den Veranstaltungs-Einstellungen definiert wurde. tag: Der Inhalt des Feldes Tag, so wie er in den Veranstaltungs-Einstellungen definiert wurde.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.