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

## Aufruf

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

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

## Authentifizierung

Folgende Header müssen gesetzt werden:

- `X-Api-key`: Haupt-API-Schlüssel (Pflicht)
- `X-Api-push`: zusätzlicher Import-Schlüssel (optional, empfohlen – bitte separat anfordern)

## Request-Body (Payload)

### 1. meta

Enthält Steuerparameter für das Importverhalten:

- **failIfExists** (Boolean): Gibt an, ob bei vorhandenem Ticketcode ein Fehler erzeugt wird oder die Daten aktualisiert werden.
- **insertAs** (Integer): Definiert den Status für neue Datensätze: 
    - `1`: bereits bestätigt
    - `2`: zu bestätigen (erfordert spätere Rückmeldung durch den Gast)
    
    *Hinweis: Wird nur bei neu angelegten Gästen berücksichtigt.*

### 2. guests

Enthält ein Array mit bis zu **100 Gast-Datensätzen**. Jeder Datensatz ist ein Key-Value-Objekt, basierend auf den Feldern aus `/metadata`.

Besonderheiten:

- **Ticketcode**: Fehlt er, wird ein neuer generiert. Ist er vorhanden, erfolgt eine Prüfung – abhängig von `failIfExists`.
- **Gates**: Falls im Metadata-Abschnitt `gates` enthalten sind, kann zusätzlich ein Array `gates` mit Gate-IDs gesetzt werden. **Ist das Array vorhandnen und fehlen in diesem Array dem Gast bereits zugewiesene Gates, werden sie entfernt.**

Beispiel-Request

```json
{
  "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]
    }
  ]
}
```

## Response

HTTP Status Codes:

- **422 Formale Fehler**: z.B. fehlendes `meta` Objekt.
- **200 OK**: Alle Datensätze wurden erfolgreich verarbeitet.
- **207 Multi-Status**: Einige Datensätze konnten nicht verarbeitet werden (Details in `results` - s.u.).

Beispiel für HTTP 422

Request

```json
{
    "meta": {
        "failIfExists": true,
        "insertAs": 3
    },
    "guests": [
        {
            "GUEST_TICKET_CODE": "223345",
            "GUEST_FIRST_NAME": "Hans",
            "GUEST_LAST_NAME": "Hermann",
            "gates": [6398]
        },
        {
            "GUEST_TICKET_CODE": "4711",
            "GUEST_FIRST_NAME": "Susi",
            "GUEST_LAST_NAME": "Sorglos",
            "gates": [6399]
        }
    ]
}
```

Response

```json
{
    "error": true,
    "message": {
        "meta.insertAs": [
            "The value may not be greater than 2."
        ]
    }
}
```


### Erfolgreiche oder Teilerfolgreiche Verarbeitung (HTTP 200, HTTP 207):

Der Response gliedert sich in zwei Bereiche:

### 1. summary

- `total`: Anzahl der übergebenen Datensätze
- `created`: neu angelegte Gäste
- `updated`: aktualisierte Gäste
- `failed`: fehlerhafte Einträge

### 2. results

Gibt für jeden Datensatz an, ob die Verarbeitung erfolgreich war oder nicht.

### Beispiel für HTTP 207

Request:

```json
{
    "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:

```json
{
    "summary": {
        "total": 4,
        "created": 0,
        "updated": 1,
        "failed": 3
    },
    "results": [
        {
            "index": 0,
            "ticketCode": "223344",
            "id": 3247987,
            "status": "updated",
            "message": 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"
        }
    ]
}
```