Übersicht

Worum es 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.

Grundlage: Swagger-Beschreibung

Diese Anleitung erläutert die veröffentlichte Swagger-Dokumentation „External API for GATEWatch“, Version 1.0.0. Die zugrunde liegende OpenAPI-Beschreibung enthält Endpunkte, Parameter, Antwortmodelle und Beispiele. Die folgenden Seiten ergänzen diese technische Referenz um den praktischen Ablauf und Fehlerbehandlung.

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, den Swagger als erforderlich ausweist.
• 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: Laut Swagger erforderlicher Import-Schlüssel (ApiPushHeader). Den passenden Wert beim Teilnehmermanagement anfordern.
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 Veranstaltung kann eine Liste erlaubter IP-Adressen hinterlegt sein. Ein eigener, nicht leerer IP-Filter der gewä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

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

In Swagger öffnen Sie den gewünschten Endpunkt. Unter Authorize hinterlegen Sie die Schlüssel; über Try it out geben Sie Parameter beziehungsweise den Request-Body ein und starten mit Execute den Aufruf. Die Bereiche Example Value und Schema zeigen Beispielwerte und die Datenstruktur. 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. DieBei Schlüsselbeiden derExportvarianten Leseantworten aus (pull und fetch) werdenlegt dagegenimmer indie derAdministration jeweiligendie Datenansichtfachlichen frei festgelegt. Sie können etwa Vorname heißenAusgabefeldnamen und kombiniertederen Inhalte fest. Ein Feld kann einen einzelnen Wert oder berechnetezusammengesetzte Inhalte enthalten. Beispielsweise kann die Administration ein Feld Name definieren, das Vor- und Nachname zusammen ausgibt. Die festen Verwaltungsfelder von pull (id, created, updated, deleted) werden zusätzlich vom Portal ergänzt.

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 Datensatz 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 oder IP-Filter prüfen. Der Body kann leer sein.
403	Bei fetch: Ein bestehender Gast erfüllt die Filterbedingungen der Datenansicht nicht.
404	Bei fetch: Kein entsprechender Gast gefunden.
422	Anfrageparameter beziehungsweise die äußere Struktur des Schreibaufrufs sind ungültig.

Die Antwortstrukturen unterscheiden sich je Endpunkt. Ein Feld error ist nicht in jeder Antwort enthalten. Bei unerwarteten Serverfehlern keine automatische Schreibwiederholung ohne Prüfung des bereits gespeicherten Ergebnisses durchführen.

Grundlage: veröffentlichte Swagger-/OpenAPI-Beschreibung, Version 1.0.0, abgerufen am 18.09.2026. Ergänzende Betriebshinweise wurden mit dem vorliegenden Portal-Quellstand abgeglichen. Die konkreten Felder, Filter, Sprachen und Schlüssel werden je Veranstaltung vereinbart.

Praxisprüfung: Am 18.09.2026 wurden auf der freigegebenen Testumgebung Metadaten, Listenabruf mit Folgeseite, Einzelabruf, Neuanlage, Aktualisierung, Bildimport und ausgewählte Fehlerfälle geprüft. Auch Vor- und Nachname wurden nach dem Schreiben in beiden Lesewegen kontrolliert. Nach Freigabe zweier Gates wurden auch die Schreibaufrufe zum Zuordnen, Ersetzen und Leeren der Gate-Auswahl sowie die Ablehnung ungültiger Gate-IDs geprüft. Die Prüfung umfasst keinegespeicherten Gate-Zuweisungen,Zuordnungen wurden dabei nicht unabhängig zurückgelesen, da in dieser Testveranstaltung keine Gates für die APIbereitgestellten freigegebenLeseansichten waren.nur Namensfelder ausgeben.

Weiter: Abruf der Metadaten.