Direkt zum Hauptinhalt

Hinzufügen und Aktualisieren von Gast-Daten (push)

Swagger-Referenz: Operation und Antwortschema öffnen.

Worum es geht

Mit push übertragen Sie bis zu 100 Gast-Datensätze pro Anfrage. Das Portal legt neue Gäste an oder aktualisiert bestehende Gäste anhand von GUEST_TICKET_CODE.

Dieser Aufruf verändert Daten. Prüfen Sie Hauptschlüssel und Veranstaltungsnamen zunächst über metadata und beginnen Sie mit abgestimmten Testdaten.

Aufruf und Header

Speichern Sie den JSON-Body in einer lokalen Datei push.json. Senden Sie ihn beispielsweise so:

curl --request POST 'https://gwatch.events/ext-api/push' \
  --header 'X-Api-x-api-key: IHR_HAUPTSCHLUESSEL' \
  --header 'X-Api-x-api-push: IHR_IMPORTSCHLUESSEL' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-binary '@push.json'

EinSwagger konfigurierterweist Import-Schlüsselfür istpush sowohl x-api-key als auch x-api-push als erforderlich undaus. mussFordern genauSie passen.beide IstSchlüssel für die VeranstaltungAnbindung kein Import-Schlüssel eingerichtet, entfernen Sie die Zeile mit X-Api-push. Ein nicht leerer Header wird in diesem Fall abgewiesen.an. Ein Flavor-Schlüssel wird bei push nicht verwendet.

Ergänzender Betriebshinweis: Die Implementierung unterstützt auch Veranstaltungen ohne konfigurierten Import-Schlüssel. Nur wenn das Teilnehmermanagement diesen Fall ausdrücklich bestätigt, lassen Sie x-api-push weg. Ein nicht leerer Wert wird bei einer solchen Konfiguration abgewiesen.

Aufbau der Anfrage

Feld Vorgabe
meta.failIfExists Erforderlicher Boolean: true weist vorhandene Ticketcodes ab; false erlaubt Aktualisierungen.
meta.insertAs Erforderliche Ganzzahl: 1 für bereits bestätigte neue Gäste, 2 für neue Gäste mit ausstehender Bestätigung. Wird nur bei Neuanlage berücksichtigt.
guests Array mit 1 bis 100 Gastobjekten. Jedes Objekt verwendet Schlüssel aus metadata.guest.

Vollständiges Beispiel für push.json aus dem Swagger-Modell pushBody:

{
  "meta": {
    "failIfExists": false,
    "insertAs": 2}2
  },
  "guests": [
    {
      "GUEST_TICKET_CODE": "TEST0001"ABC123",
      "GUEST_FIRST_NAME": "Erika"Max",
      "GUEST_LAST_NAME": "Musterfrau"Mustermann",
      "GUEST_LOCALE"GUEST_EMAIL": "de"max@example.com",
      "GUEST_ACTIVE": true,
      "gates": [6398]
        1,
        3
      ]
    },
    {
      "GUEST_FIRST_NAME": "Simone",
      "GUEST_LAST_NAME": "Pfeifer",
      "GUEST_EMAIL": "simone@example.com"
    }
  ]
}

Die benutzerdefinierten NamensfelderNamens- und E-Mail-Felder sowie die Gate-IDIDs 63981 und 3 sind Beispiele. Sie müssen in Ihren Metadaten vorkommen. Wenn keine Gate-Zuordnung geändert werden soll, lassen Sie gates weg.

Neuanlage oder Aktualisierung?

Situation Verarbeitung
Ticketcode fehlt Das Portal erzeugt einen neuen Code und legt einen Gast an.
Ticketcode vorhanden, aber kein bestehender Gast mit diesem Code gefunden Ein neuer Gast wird mit diesem Code angelegt, sofern die Validierung erfolgreich ist.
Ticketcode gefunden und failIfExists=false Der vorhandene Gast wird aktualisiert.
Ticketcode gefunden und failIfExists=true Der Datensatz schlägt fehl; es wird kein zweiter Gast mit diesem Code angelegt.

Die Zuordnung erfolgt über den Ticketcode innerhalb der Veranstaltung, nicht über E-Mail-Adresse, Name oder die Datenbank-ID. Übermitteln Sie den Ticketcode als Zeichenfolge. Er muss den Restriktionen aus metadata entsprechen.

Bei einem Update werden die gesendeten Felder verarbeitet. Weglassen und null sind nicht dasselbe: Weggelassene Felder werden nicht gezielt überschrieben; ein ausdrücklich übergebenes null kann bei zulässigen Feldern einen Wert leeren. Bei nullable=false ist null ungültig. Prüfen Sie beabsichtigtes Leeren je Feldtyp zunächst mit Testdaten.

insertAs setzt keinen bestehenden Gast nachträglich auf einen anderen Teilnahmestatus. Dafür ist dieser Parameter nicht vorgesehen.

Gate-Zuordnungen bewusst ersetzen

Inhalt im Gastobjekt Wirkung nach erfolgreicher Gastverarbeitung
Kein gates-Schlüssel Vorhandene Zuordnungen bleiben erhalten.
"gates": [6398, 6399] Die Auswahl wird durch diese IDs ersetzt. Bereits zugeordnete Gates, die fehlen, werden entfernt.
"gates": [] Alle vorhandenen Gate-Zuordnungen werden entfernt.

Verwenden Sie ausschließlich freigegebene Gate-IDs aus metadata.gates. Wenn dort keine Gates verfügbar sind, lassen Sie den Schlüssel weg; im aktuellen API-Verhalten ist er dann kein freigegebenes Eingabefeld.

Die Ersetzung betrifft auch vorhandene Zuordnungen, die in Ihrer übermittelten Auswahl nicht vorkommen. Sie ist kein reines Hinzufügen. Soll nur ein Gate ergänzt werden, muss die vollständige gewünschte Auswahl abgestimmt sein. Eine Gate-Zuordnung über push ist kein Ein- oder Ausgangsscan.

Antwort und Einzelergebnisse

Bei verarbeiteten Anfragen enthält die Antwort summary und results, ohne zusätzliches oberstes error-Feld.

Feld Bedeutung
summary.total Zahl der übergebenen Gastobjekte.
summary.created Zahl erfolgreich neu angelegter Gäste.
summary.updated Zahl erfolgreich aktualisierter Gäste.
summary.failed Zahl fehlgeschlagener Gastobjekte.
results[].index Position in Ihrem Eingabearray, beginnend bei 0.
results[].status created, updated oder failed.
results[].ticketCode / id Zugeordneter Ticketcode und Gast-ID; bei Fehlern gegebenenfalls null.
results[].message Bei Erfolg null, bei Fehlern eine Zeichenfolge oder ein Objekt mit Feldmeldungen.

Beispiel einer erfolgreichen NeuanlageVerarbeitung mit HTTP 200:200 aus dem Swagger-Modell pushSuccess (eigenständiges Antwortbeispiel, keine Zuordnung zum obigen Request):

{
  "summary": {
    "total": 1,2,
    "created": 1,
    "updated": 0,1,
    "failed": 0}0
  },
  "results": [
    {
      "index": 0,
      "ticketCode": "TEST0001"223344",
      "id": 12345,3247987,
      "status": "updated",
      "message": null
    },
    {
      "index": 1,
      "ticketCode": "223323",
      "id": 2343234,
      "status": "created",
      "message": null}null
    }
  ]
}

HTTP 207: Ergebnisse einzeln behandeln

Sobald mindestens ein Datensatz fehlschlägt, lautet der HTTP-Status 207, auch wenn alle Datensätze fehlschlagen. Erfolgreiche Datensätze werden dadurch nicht insgesamt zurückgerollt.

Beispiel einer Anfrage mit einem erfolgreichen Update und einem nicht freigegebenen Eingabeschlüssel:

{
  "summary": {"total": 2, "created": 0, "updated": 1, "failed": 1},
  "results": [
    {"index": 0, "ticketCode": "TEST0001", "id": 12345, "status": "updated", "message": null},
    {"index": 1, "ticketCode": null, "id": null, "status": "failed", "message": "The following keys are not available: TICKET_CODE"}
  ]
}

TICKET_CODE ist kein Ersatz für GUEST_TICKET_CODE. Nutzen Sie index, um Fehler eindeutig dem gesendeten Datensatz zuzuordnen; bei einem Fehler muss ticketCode nicht den ursprünglich übergebenen Wert enthalten.

HTTP 422: Anfrage korrigieren

Fehlende Steuerparameter, ein unzulässiges insertAs, eine leere Gästeliste oder mehr als 100 Datensätze führen zur Ablehnung der äußeren Anfrage. Beispiel:

{
  "error": true,
  "message": {"meta.insertAs": ["The meta.insertAsvalue field mustmay not be greater than 2."]}
}

Der Meldungstext ist beispielhaft. Verwenden Sie Feldschlüssel und HTTP-Status für die Auswertung. Fehler innerhalb einzelner Gastobjekte werden dagegen in der Regel über results und HTTP 207 gemeldet. Senden Sie stets echte Gastobjekte; andere Array-Inhalte sind kein unterstütztes Eingabeformat.

Wiederholungen und Teiländerungen

  • Speichern Sie das Ergebnis einschließlich index, Ticketcode und ID.
  • Wiederholen Sie eine fehlgeschlagene Anfrage ohne eigene Ticketcodes nicht blind: Bereits angelegte Gäste könnten erneut angelegt werden.
  • Auch eine Fehlermeldung bei einem Update garantiert nicht, dass sämtliche Felder des Gastes unverändert geblieben sind. Die Speicherung vorhandener Gäste ist nicht als atomarer Gesamtvorgang abgesichert. Prüfen Sie den aktuellen Stand, bevor Sie korrigiert erneut senden.
  • Korrigieren Sie fehlgeschlagene Datensätze gezielt. Ein Timeout auf Ihrer Seite beweist nicht, dass der Server nichts gespeichert hat.

Häufige Fehler

Problem Prüfung
HTTP 401 Hauptschlüssel, Archivstatus, allgemeinen IP-Filter und exakt passenden Import-Schlüssel prüfen.
Unbekannter Feldschlüssel Aktuelle metadata.guest verwenden, nicht die frei vereinbarten Lesefelder.
Listenwert abgewiesen items[].key senden, nicht value oder values.
Bild wird abgewiesen Gültige eingebettete Bild-Data-URI und freigegebenes Bildfeld prüfen.
Gate-ID ungültig ID muss für diese Veranstaltung in metadata.gates vorkommen.
Bestehender Gast abgewiesen failIfExists prüfen. Nur bei gewolltem Update auf false setzen.
Werte nach Update unerwartet leer Gesendete null- oder Leerwerte prüfen. Unveränderte Felder weglassen.
Alte Gate-Zuordnungen fehlen gates ersetzt die gesamte Auswahl. Vollständige gewünschte Zuordnung abstimmen.

Vor dem produktiven Einsatz prüfen

  1. Veranstaltung und Feldliste über metadata bestätigen.
  2. Einen Testgast anlegen und zurückgegebenen Ticketcode speichern.
  3. Denselben Gast mit failIfExists=false gezielt aktualisieren.
  4. Fehlerfall mit failIfExists=true sowie Feldvalidierung prüfen.
  5. Gate-Ersetzung nur mit abgestimmten Testzuordnungen testen.
  6. Antwortauswertung für HTTP 200, 207, 401 und 422 vorsehen.

Zurück: Einzelabruf.
Zum Einstieg: Übersicht.

nach oben