Übersicht

ZugangWorum zures geht

Über die externe API verbinden Sie ein anderes System mit einer GATEWatch-Veranstaltung. Sie können verfügbare Eingabefelder ermitteln, Gästedaten auslesen sowie Gäste anlegen und aktualisieren. Diese Anleitung richtet sich an die technische Betreuung der Anbindung.

Die vier Endpunkte

Die Basisadresse für die hier gezeigten Aufrufe lautet https://gwatch.events/ext-api.

Methode Endpunkt Aufgabe Anleitung GET /metadata Importierbare Felder, Sprachen und freigegebene Gates ermitteln. Metadaten GET /pull Gästeliste in Seiten abrufen; optional nach Änderungen filtern. Listenabruf GET /fetch Einen Gast über seinen Ticketcode abrufen. Einzelabruf POST /push Gäste anlegen oder anhand ihres Ticketcodes aktualisieren. Gäste schreiben

Die GET-Aufrufe verwenden URL-Parameter und benötigen keinen JSON-Body. Bei push senden Sie den Body als JSON mit Content-Type: application/json. Antworten sind grundsätzlich JSON; insbesondere HTTP 401 kann jedoch einen leeren Body haben. Werten Sie deshalb zuerst den HTTP-Status aus.

Voraussetzungen und Zugang

Fordern Sie beim zuständigen Teilnehmermanagement folgende Angaben an:

Den API-Hauptschlüssel für die richtige, nicht archivierte Veranstaltung. Für pull und fetch eine aktive Datenansicht (Flavor) des passenden Typs und deren Schlüssel. Für push den zusätzlichen Import-Schlüssel, sofern eingerichtet. Die Freigabe der ausgehenden IP-Adresse Ihres Servers, falls ein IP-Filter besteht. Die vereinbarten Ausgabefelder sowie die für den Import freigegebenen Felder und Gates.

Header und ihre Bedeutung

Header Verwendung X-Api-key Bei allen vier Endpunkten erforderlich. Der Schlüssel bestimmt die Veranstaltung; eine zusätzliche Veranstaltungs-ID wird nicht übergeben. X-Api-flavor Bei pull und fetch: Schlüssel der jeweiligen Datenansicht. Weglassen funktioniert nur, wenn eine aktive Ansicht mit leerem Schlüssel und passendem Typ eingerichtet ist. X-Api-push Bei push: Muss dem konfigurierten Import-Schlüssel entsprechen. Ist keiner eingerichtet, lassen Sie diesen Header weg. Ein beliebiger zusätzlicher Wert wird abgewiesen. Accept Verwenden Sie application/json. Content-Type Bei push: application/json.

Ein Flavor für pull ist nicht automatisch für fetch verwendbar. Die Datenansichten werden getrennt nach Endpunkttyp konfiguriert. metadata benötigt keinen Flavor.

Verwenden Sie Schlüssel in den Headern und bewahren Sie sie in der serverseitigen Konfiguration auf. Die Beispiele enthalten nur Platzhalter; sie sind vor einem eigenen Test zu ersetzen.

IP-Filter

Für die NutzungVeranstaltung kann eine Liste erlaubter IP-Adressen hinterlegt sein. Ein eigener, nicht leerer IP-Filter der APIgewählten Datenansicht ersetzt bei pull beziehungsweise fetch den allgemeinen Filter. Ohne eigenen Filter gilt der allgemeine Filter.

Geprüft wird die vom Portal ermittelte IP-Adresse der Anfrage. Lassen Sie deshalb auch die tatsächliche ausgehende Adresse Ihrer Testumgebung freigeben. Die aktuelle Implementierung vergleicht einzelne Adressen; CIDR-Netze und Wildcards sind keine unterstützte Schreibweise dieser Filter.

Empfohlener Einstieg

Rufen Sie metadata ab und kontrollieren Sie den Veranstaltungsnamen. Stimmen Sie die gewünschte Leseansicht mit dem Teilnehmermanagement ab. Prüfen Sie pull mit einem kleinen limit oder fetch mit einem bekannten Test-Ticketcode. Ordnen Sie die Felder Ihres Systems den tatsächlich gelieferten Feldschlüsseln zu. Testen Sie push mit abgestimmten Testdaten und kontrollieren Sie jedes Einzelergebnis.

Die API-Testoberfläche bietet ebenfalls Testaufrufe. Ein push-Aufruf schreibt echte Daten in die über den Hauptschlüssel ausgewählte Veranstaltung. Verwenden Sie dafür eine vereinbarte Testveranstaltung.

Schreibfelder und Lesefelder unterscheiden

metadata.guest beschreibt die zulässigen Eingabeschlüssel für push, beispielsweise GUEST_FIRST_NAME. Die Schlüssel der Leseantworten aus pull und fetch werden dagegen in der jeweiligen Datenansicht frei festgelegt. Sie können etwa Vorname heißen und kombinierte oder berechnete Inhalte enthalten.

Kopieren Sie eine Leseantwort daher nicht unverändert in einen Schreibaufruf. Auch Datums-, Listen- und Ja/Nein-Ausgaben sind nicht automatisch geeignete Eingabewerte.

HTTP-Status im Überblick

Status Bedeutung 200 Erfolgreicher Abruf oder vollständig erfolgreicher push. 207 Bei push ist mindestens ein gültigerDatensatz API-fehlgeschlagen; auch alle Datensätze können betroffen sein. summary und results auswerten. 401 Zugang abgewiesen: Hauptschlüssel, Archivstatus, Flavor-Typ/Aktivierung, Import-Schlüssel erforderlichoder (Hauptschlüssel).IP-Filter Dieserprüfen. Der Body kann überleer dassein. zuständige Teilnehmermanagementbezogen403 werden.Bei Abhängigfetch: vomEin Anwendungsfallbestehender könnenGast zusätzlicherfüllt weiteredie Schlüssel zur Verfügung gestellt werden. Die Verwendung und FunktionFilterbedingungen der einzelnenDatenansicht Schlüsselnicht. wird imweiteren404 VerlaufBei dieserfetch: DokumentationKein erläutert.entsprechender KannGast gefunden. 422 Anfrageparameter beziehungsweise die Authentifizierungäußere nichtStruktur erfolgreichdes durchgeführtSchreibaufrufs werdensind kommtungültig. es zu einem HTTP 401 Fehler.

Zusätzlich kann der Zugriff auf die API über eine IP-Filterung eingeschränkt werden. Es wird empfohlen, die IP-Adresse(n) der anfragenden Server (inkl. Testumgebungen) im Vorfeld zu definieren und bereitzuhalten. Schlägt die Prüfung der IP Adresse fehl, kommt es zu einem HTTP 401 Fehler.

Die APIAntwortstrukturen verwendetunterscheiden JSONsich (JavaScriptje ObjectEndpunkt. Notation)Ein alsFeld Austauschformat.error Anfragenist annicht diein APIjeder sowieAntwort dieenthalten. vonBei ihrunerwarteten zurückgegebenenServerfehlern Antwortenkeine müssenautomatische imSchreibwiederholung JSON-Formatohne strukturiertPrüfung bzw.des verarbeitetbereits werden.gespeicherten Ergebnisses durchführen.

Fachlicher API-EndpunkteAbgleich: vorliegender Portal-Quellstand vom 18.09.2026. Die APIkonkreten bietetFelder, dreiFilter, dedizierte Endpunkte zur Interaktion: https://gwatch.events/ext-api/metadata
Zweck: Abfrage verfügbarer MetadatenSprachen und Konfigurationsinformationen.Schlüssel https://gwatch.events/ext-api/pull
werden je Veranstaltung vereinbart.

Zweck:Weiter: Abruf vorhandener Gast-Daten. https://gwatch.events/ext-api/push
Zweck: Übertragung (Hinzufügen oder Aktualisieren) von Gast-Daten.

Weitere Informationen

Die genaue Struktur der Anfragen, das erwartete JSON-Format sowie mögliche Fehlermeldungen und Antwort-Codes werden auf den folgenden Seiten ausführlich beschrieben.Metadaten

.

Falls Sie die API online testen möchten, besuchen Sie:
https://gwatch.events/ext-api