Buchungs- und Teilnehmerangaben mit der Booking API erfassen

Veranstalter können für jede Buchung oder jedes Ticket Fragen stellen, zum Beispiel nach Teilnehmernamen, einem Geburtsdatum oder Ernährungswünschen. Mit dieser Anleitung zeigen Sie diese Fragen in Ihrem Checkout an und speichern die Antworten vor der Zahlung.

Die vor der Zahlung erforderlichen Fragen müssen beantwortet werden, bevor Sie den Checkout abschließen, auch wenn Sie die gehostete Zahlungsseite nutzen. Sollte Ihre Integration diese Angaben nicht erfassen können, nutzen Sie stattdessen den gehosteten Online-Shop des Veranstalters für die Buchung.

Bevor Sie beginnen

• Ein Warenkorb mit mindestens einer Position und sein Warenkorb-Token.
• Der Schnellstart für die Booking API erklärt Warenkörbe und Tokens.

Prüfen, ob der Warenkorb Fragen enthält

Lesen Sie customFieldsCompletion am Warenkorb. Ist allRequiredComplete gleich false, sind noch Pflichtfragen offen. Fragen Sie in derselben Abfrage customFieldsCollectionToken ab; Sie brauchen dieses Token, um die Fragen zu lesen und zu beantworten. Jede Abfrage erzeugt ein neues Token. Fragen Sie es deshalb erst ab, wenn Sie mit dem Erfassen der Antworten beginnen, und nicht bei jeder Aktualisierung des Warenkorbs.

query CartQuestions($id: IdOrNumberOrToken!) {
  request(id: $id) {
    customFieldsCompletion {
      hasCustomFields
      allRequiredComplete
    }
    customFieldsCollectionToken(requiredByStage: BEFORE_PAYMENT)
  }
}

requiredByStage: BEFORE_PAYMENT umfasst alle Fragen, die vor der Zahlung beantwortet sein müssen. Das Token ist 24 Stunden gültig; lesen Sie danach ein neues.

Offene Fragen lesen

query OpenQuestions($token: Token!) {
  requestCustomFields(requestId: $token) {
    openCustomFields {
      customizableId
      customizableType
      offerableNameTranslated
      pricingNameTranslated
      customFieldSets {
        id
        legendTranslated
        descTranslated
        inputs {
          id
          labelTranslated
          descTranslated
          type
          required
          mapping
          options {
            value
            labelTranslated
          }
        }
      }
    }
  }
}

Jeder Eintrag in openCustomFields steht für einen Satz Antworten, den Sie erfassen:

customFieldSets fasst die Fragen unter einer Überschrift aus legendTranslated zusammen. Zeigen Sie die Fragen in der zurückgegebenen Reihenfolge an.

Formular aufbauen

Wählen Sie das Formularelement anhand von type und senden Sie die Antwort als Text:

mapping zeigt, ob eine Antwort eine Standardangabe zum Teilnehmer wie FIRST_NAME oder LAST_NAME füllt; CUSTOM ist eine vom Veranstalter definierte Frage.

Antworten speichern

Senden Sie die Antworten für jeweils einen Eintrag aus openCustomFields, mit einem Element pro Fragengruppe:

mutation SaveAnswers($input: RequestCustomFieldsCollectionSubmitInput!) {
  requestCustomFieldsCollectionSubmit(input: $input) {
    customFieldsResponses {
      id
      completionState
    }
    errors {
      key
      message
      messageTranslated
    }
  }
}

{
  "input": {
    "requestId": "<customFieldsCollectionToken>",
    "customFieldsResponses": [
      {
        "customizableId": "<customizableId>",
        "customizableType": "ATTENDANCE",
        "fieldSetId": "<customFieldSets.id>",
        "values": [{ "inputId": "<inputs.id>", "value": "Alex" }]
      }
    ]
  }
}

Sind die Antworten gespeichert, ist completionState gleich REQUIREMENTS_MET. Lesen Sie die offenen Fragen erneut und wiederholen Sie den Vorgang, bis openCustomFields leer ist. Schließen Sie dann den Checkout ab.

Enthält eine Position mehrere Tickets derselben Preiskategorie, erscheinen sie in openCustomFields als ein Eintrag. Jedes Speichern füllt das nächste Ticket aus. Lesen Sie die Liste deshalb nach jedem Speichern erneut, bis der Eintrag verschwindet.

Fragen, die die Booking API noch nicht beantworten kann

Datei-Uploads (FILE), Verzichtserklärungen (WAIVER) und Fragen zum Kunden (CONTACT) können nicht über die Booking API übermittelt werden. Sind diese vor der Zahlung erforderlich, unterstützt diese Konfiguration keinen vollständigen Headless-Checkout: Der Checkout gibt custom_fields_incomplete zurück und liefert weder eine Rechnung noch paymentLink.

Nutzen Sie für diese Buchungen von Beginn an den gehosteten Online-Shop des Veranstalters, damit der Kunde die erforderlichen Angaben vor dem Checkout machen kann. Schließen Sie den API-Checkout nicht in der Erwartung ab, dass ein Zahlungslink diese Angaben erfasst.

Fehler

Je nach Einstellungen des Veranstalters schlägt der Checkout mit custom_fields_incomplete fehl, solange Pflichtfragen offen sind. Beantworten Sie die Fragen und schließen Sie den Checkout erneut ab.

Verwandte Artikel

• Checkout abschließen und Zahlung mit der Booking API abwickeln
• So funktioniert die Booking API
• Fehlercodes der Booking API
• Kunden- und Teilnehmerdaten an der Kasse erfassen