# Abruf der Metadaten (metadata)

**Swagger-Referenz:** [Operation und Antwortschema öffnen](https://gwatch.events/ext-api#//get_ext_api_metadata).

## Worum es geht

`metadata` beschreibt die Veranstaltung und die verfügbaren **Eingabefelder für `push`**. Rufen Sie diese Angaben vor der Einrichtung eines Imports ab und prüfen Sie sie erneut, wenn die Veranstaltungskonfiguration geändert wurde.

## Aufruf

```bash
curl --request GET 'https://gwatch.events/ext-api/metadata' \
  --header 'x-api-key: IHR_HAUPTSCHLUESSEL' \
  --header 'Accept: application/json'

```

Benötigt werden der Hauptschlüssel und gegebenenfalls die Freigabe Ihrer IP-Adresse. Ein Flavor- oder Import-Schlüssel ist für diesen Aufruf nicht erforderlich.

## Aufbau der Antwort

Die Antwort enthält direkt die Bereiche `event`, `guest` und `gates`, ohne zusätzliches `error`-Feld.

<table id="bkmrk-bereich-inhalt-event"><thead><tr><th>Bereich</th><th>Inhalt</th></tr></thead><tbody><tr><td>`event`</td><td>Veranstaltungsname, Datum, Standardlänge automatisch erzeugter Ticketcodes und verfügbare Sprachen.</td></tr><tr><td>`guest`</td><td>Array der importierbaren Felder mit `key`, `name`, `type` und gegebenenfalls `restrictions` oder `items`.</td></tr><tr><td>`gates`</td><td>Array der für die API freigegebenen Gates mit `id` und `name`. Es kann leer sein.</td></tr></tbody></table>

Die folgende gültige JSON-Darstellung ist ein **gekürztes Beispiel nach den Swagger-Modellen** mit einer Auswahl von Feldern. Beispielgrenzen sind keine festen Vorgaben für Ihre Veranstaltung:

```json
{
  "event": {
    "name": "IT seminar",
    "date": "2025-05-31",
    "defaultTicketCodeLength": 10,
    "locales": [
      "de",
      "en"
    ]
  },
  "guest": [
    {
      "key": "GUEST_TICKET_CODE",
      "name": "Ticket code",
      "type": "singleLineText",
      "restrictions": {
        "nullable": false,
        "unique": true,
        "min": 6,
        "max": 12
      }
    },
    {
      "key": "GUEST_LOCALE",
      "name": "Locale",
      "type": "list",
      "items": [
        {
          "key": "de",
          "value": "Deutsch"
        },
        {
          "key": "en",
          "value": "English"
        }
      ],
      "restrictions": {
        "nullable": false
      }
    },
    {
      "key": "GUEST_NAME",
      "name": "Name",
      "type": "singleLineText",
      "restrictions": {
        "max": 65535
      }
    }
  ],
  "gates": [
    {
      "id": 6398,
      "name": "Sicherheit von Websites"
    },
    {
      "id": 6399,
      "name": "Anti-Viren Software aktuell"
    }
  ]
}

```

## Feldschlüssel und Einschränkungen

- **`key`** wird beim Schreiben unverändert als JSON-Schlüssel verwendet. Groß-/Kleinschreibung beachten.
- **`name`** ist die lesbare Bezeichnung zur Abstimmung mit dem Teilnehmermanagement.
- **`type`** bestimmt das vorgesehene Eingabeformat.
- **`restrictions`** beschreibt zusätzliche Grenzen, etwa `min`, `max`, `nullable`, `unique`, `maxWidth` oder `maxHeight`.

`nullable: false` bedeutet: Wenn Sie das Feld senden, darf sein Wert nicht `null` sein. Das ist keine generelle Pflicht, das Feld in jedem Datensatz zu senden. Weggelassene Felder werden beim Aktualisieren nicht gezielt überschrieben; bei neuen Gästen greifen die jeweiligen Vorgaben beziehungsweise Standardwerte.

`defaultTicketCodeLength` ist die Standardlänge generierter Codes. Eigene Codes können davon abweichen, müssen aber die Restriktionen von `GUEST_TICKET_CODE` einhalten. Senden Sie Ticketcodes als Zeichenfolge, damit führende Nullen erhalten bleiben.

Zu den Standardfeldern gehören `GUEST_TICKET_CODE`, `GUEST_LOGIN`, `GUEST_PASSWORD`, `GUEST_LOCALE`, `GUEST_ACTIVE`, `GUEST_VALID_FROM` und `GUEST_VALID_TO`. Weitere Gästefelder erscheinen nur bei entsprechender API-Freigabe. Verwenden Sie die tatsächlich gelieferte Feldliste.

## Eingabeformate

<table id="bkmrk-typ-empfohlener-json"><thead><tr><th>Typ</th><th>Empfohlener JSON-Wert</th></tr></thead><tbody><tr><td>`singleLineText`</td><td>Zeichenfolge ohne Zeilenumbruch.</td></tr><tr><td>`multiLineText`</td><td>Zeichenfolge; Zeilenumbrüche in JSON als `\n`.</td></tr><tr><td>`email`</td><td>Formal gültige E-Mail-Adresse.</td></tr><tr><td>`url`</td><td>Vollständige gültige URL.</td></tr><tr><td>`numeric`</td><td>Zahl mit Dezimalpunkt, beispielsweise `12.5`.</td></tr><tr><td>`integer`</td><td>Ganzzahl, beispielsweise `3`.</td></tr><tr><td>`boolean`</td><td>JSON-Werte `true` oder `false`. Verlassen Sie sich nicht auf lokalisierte Zeichenfolgen wie `Ja` oder `Nein`.</td></tr><tr><td>`date`</td><td>Zeichenfolge im Format `YYYY-MM-DD`.</td></tr><tr><td>`dateTime`</td><td>Zeichenfolge im Format `YYYY-MM-DDTHH:MM:SS`. Die verwendete Portal-Zeitzone vor der Anbindung abstimmen.</td></tr><tr><td>`list`</td><td>Einen der unter `items` gelieferten **Schlüssel** verwenden.</td></tr><tr><td>`image`</td><td>Bild als eingebettete Data-URI, beispielsweise mit dem Präfix `data:image/png;base64,` und anschließendem Base64-Bildinhalt.</td></tr></tbody></table>

Bildfelder enthalten Größenangaben in den Restriktionen. Die Bildverarbeitung kann zu große Bilder beim Speichern proportional verkleinern. Eine gewöhnliche externe Bild-URL ist nicht das hier beschriebene Importformat.

## Listen mit mehreren Sprachen

Bei benutzerdefinierten Listen kann ein Eintrag statt `value` eine sprachabhängige Zuordnung `values` enthalten:

```json
{
  "key": "GUEST_FOOD",
  "name": "Food",
  "type": "list",
  "items": [
    {
      "key": "ID_164h656yn",
      "values": {
        "de": "Keine Einschränkungen",
        "en": "No restrictions"
      }
    },
    {
      "key": "ID_6rkyfap8y",
      "values": {
        "de": "Vegetarisch",
        "en": "Veggie"
      }
    },
    {
      "key": "ID_ncg2151l7",
      "values": {
        "de": "Vegan",
        "en": "Vegan"
      }
    }
  ],
  "restrictions": {
    "nullable": true
  }
}

```

Beim Schreiben verwenden Sie hier beispielsweise `"GUEST_FOOD": "ID_6rkyfap8y"` für die vegetarische Auswahl. Die sichtbare Bezeichnung wird nicht als Eingabeschlüssel verwendet. Der Feldname ist beispielhaft und muss in Ihren Metadaten tatsächlich vorkommen.

## Gates verwenden

Gates können Sessions, Veranstaltungstage oder andere Zugangsbereiche darstellen. Nur die unter `gates` aufgeführten IDs sind für die API-Zuweisung freigegeben. Wie Sie eine Gate-Auswahl übermitteln und was beim Weglassen oder Leeren passiert, beschreibt [push](https://doc.gwatch.events/books/externes-api/page/hinzufugen-und-aktualisieren-von-gast-daten-push).

## Typische Probleme

<table id="bkmrk-problem-pr%C3%BCfung-http"><thead><tr><th>Problem</th><th>Prüfung</th></tr></thead><tbody><tr><td>HTTP 401</td><td>Hauptschlüssel, Veranstaltung und allgemeinen IP-Filter prüfen. Archivierte Veranstaltungen sind ausgeschlossen.</td></tr><tr><td>Ein Gästefeld fehlt</td><td>API-Freigabe des Feldes prüfen lassen.</td></tr><tr><td>Ein Gate fehlt</td><td>API-Freigabe des Gates prüfen lassen.</td></tr><tr><td>Ausgabefeld aus `pull` ist hier nicht enthalten</td><td>Lesefelder und Eingabeschlüssel sind getrennte Konfigurationen. Zuordnung vereinbaren.</td></tr></tbody></table>

**Weiter:** [Gästeliste abrufen](https://doc.gwatch.events/books/externes-api/page/abruf-von-gast-daten-als-liste-pull).  
**Zurück:** [Übersicht](https://doc.gwatch.events/books/externes-api/page/ubersicht).