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

AufrufWorum es geht

DieMit Übertragung erfolgt über eine HTTP-POST-Anfrage an folgende URL:

https://gwatch.events/ext-api/push

Authentifizierung

Folgende Header müssen gesetzt werden:

Request-Body (Payload)

1. meta

Enthält Steuerparameter für das Importverhalten:

2. guests

Enthält ein Array mitSie bis zu 100 Gast-DatensätzenDatensätze pro Anfrage. JederDas DatensatzPortal istlegt einneue Key-Value-Objekt,Gäste basierendan aufoder denaktualisiert Feldernbestehende ausGäste anhand von /metadataGUEST_TICKET_CODE.

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

Aufruf

Speichern wirdSie einden neuerJSON-Body generiert.in einer lokalen Datei push.json. Senden Sie ihn beispielsweise so:

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

Ein konfigurierter Import-Schlüssel ist erforderlich und muss genau passen. Ist erfür vorhanden,die erfolgtVeranstaltung einekein PrüfungImport-Schlüssel –eingerichtet, abhängigentfernen vonSie failIfExists.

{
  "meta": {
    "failIfExists": false, "insertAs": 2
  },
  "guests": [
    {
      "GUEST_FIRST_NAME": "Max",
      "GUEST_LAST_NAME": "Mustermann",
      "GUEST_EMAIL": "max@example.com",
      "GUEST_TICKET_CODE": "ABC123",
      "gates": [1, 3]
    }
  ]
}

Beispiel für HTTP 422

Request

{
    "meta": {
        "failIfExists": true,
        "insertAs": 3
    }2},
  "guests": [
    {
      "GUEST_TICKET_CODE": "223345"TEST0001",
      "GUEST_FIRST_NAME": "Hans"Erika",
      "GUEST_LAST_NAME": "Hermann"Musterfrau",
      "GUEST_LOCALE": "de",
      "GUEST_ACTIVE": true,
      "gates": [6398]
    },
  {]
"GUEST_TICKET_CODE":}
"4711",

Die "Susi",benutzerdefinierten "GUEST_LAST_NAME":Namensfelder "Sorglos",und Gate-ID 6398 sind Beispiele. Sie müssen in Ihren Metadaten vorkommen. Wenn keine Gate-Zuordnung geändert werden soll, lassen Sie gates weg.

Neuanlage oder Aktualisierung?

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

Response

diese IDs ersetzt. Bereits zugeordnete Gates, die fehlen, werden entfernt.

Verwenden }Sie }ausschließlich freigegebene Gate-IDs aus metadata.gates.

Erfolgreichedort 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 TeilerfolgreicheAusgangsscan.

Antwort (HTTPund 200, HTTP 207):Einzelergebnisse

DerBei Responseverarbeiteten gliedertAnfragen sichenthält indie zweiAntwort Bereiche:summary und results, ohne zusätzliches oberstes error-Feld.

1.

• Feld Bedeutung

2./ results

Gibt

Objekt mit Feldmeldungen.

Beispiel füreiner erfolgreichen Neuanlage mit HTTP 207

Request:

{
    "meta": {
        "failIfExists": false,
        "insertAs": 2
    },
    "guests": [
        {
            "GUEST_TICKET_CODE": "223344",
            "GUEST_FIRST_NAME": "Hans",
            "GUEST_LAST_NAME": "Hermann",
            "GUEST_EMAIL": "didi@aol.com",
            "gates": [6398]
        },
        {
            "GUEST_FIRST_NAME": "Frank",
            "GUEST_LAST_NAME": "Fuhrmann",
            "GUEST_EMAIL": "ffuhrmann@aol",
            "gates": [6398]
        },
        {
            "GUEST_TICKET_CODE": "4711",
            "GUEST_FIRST_NAME": "Susi",
            "GUEST_LAST_NAME": "Sorglos",
            "gates": [6399,4]
        },
        {
            "TICKET_CODE": "4712",
            "GUEST_FIRST_NAME": "Didi",
            "GUEST_LAST_NAME": "Dröge",
            "gates": [6399]
        }
    ]
}

Response:200:

{
  "summary": {
        "total": 4,1, "created": 1, "updated": 0, "failed": 0},
  "results": [
    {"index": 0, "ticketCode": "TEST0001", "id": 12345, "status": "created", "message": 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": 3
    }1},
  "results": [
    {
            "index": 0, "ticketCode": "223344"TEST0001", "id": 3247987,12345, "status": "updated", "message": null
        }null},
    {
            "index": 1,
            "ticketCode": null,
            "id": null,
            "status": "failed",
            "message": {
                "GUEST_EMAIL": [
                    "Please enter a valid email address."
                ]
            }
        },
        {
            "index": 2,
            "ticketCode": "4711",
            "id": 3247986,
            "status": "failed",
            "message": {
                "gates.1": [
                    "The selected gates.1 is invalid."
                ]
            }
        },
        {
            "index": 3, "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.insertAs field must 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

Häufige Fehler

Vor dem produktiven Einsatz prüfen

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