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.

Fragen zu Artikeln und Gutscheinen

Warenkorbpositionen für Artikel und Gutscheine verwenden denselben Ablauf zur Erfassung von Fragen wie Veranstaltungsbuchungen. Eine BOOKING-Fragengruppe wird einmal pro Warenkorbposition beantwortet, auch wenn die Menge größer als eins ist. Eine ATTENDEE-Gruppe gilt für jeden für diese Position erstellten Teilnehmerdatensatz. Verwenden Sie Fragen zur Buchung für Informationen, die für den gesamten Kauf gelten; verwenden Sie Teilnehmerfragen für Details, die sich auf ein einzelnes Ticket oder einen einzelnen Gutschein beziehen.

Um eine vorhandene Fragengruppe einem Artikel oder Gutschein zuzuweisen, kann eine Mitarbeiterintegration die GraphQL-API der Anwendung mit Mitarbeiter-Authentifizierung aufrufen. Dieser Konfigurationsvorgang erfordert eine Mitarbeiterberechtigung für die Zuweisung benutzerdefinierter Felder; ein Warenkorb-Token reicht hierfür nicht aus.

mutation AssignQuestions($input: CustomFieldsOfferableFieldSetCreateInput!) {
  customFieldsOfferableFieldSetCreate(input: $input) {
    customFieldsOfferableFieldSet {
      id
      position
    }
    errors {
      key
      messages
    }
  }
}

{
  "input": {
    "offerableType": "VOUCHER_CONFIGURATION",
    "offerableId": "<voucher ID>",
    "fieldSetId": "<question group ID>"
  }
}

Verwenden Sie PRODUCT und die Artikel-ID für einen Artikel. Lesen Sie customFieldsFieldSets aus Product oder VoucherConfiguration aus, um deren Fragengruppen zu erhalten, und customFieldsOfferableFieldSets für Zuordnungs-IDs und Anzeigepositionen. Durch das Duplizieren eines der beiden Angebote bleiben die Zuordnungen der Fragengruppen erhalten.

Antworten in Vorlagen verwenden

In Vorlagen mit dem Kontext einer Warenkorbposition, eines Tickets oder eines Gutscheins fügt {{request_item_custom_field_123}} die Antwort zur Buchung für die Eingabe-ID 123 ein. {{attendance_custom_field_456}} fügt die Antwort des Teilnehmers für die Eingabe-ID 456 ein, sofern ein Teilnehmerdatensatz vorliegt. Diese Nummern identifizieren einzelne Eingaben, nicht Fragengruppen.

Für eine E-Mail zu einem Vorgang fügen Sie die Antworten in die Schleife über die Warenkorbpositionen ein:

{{#request_item_context}} {{#is_request_item_custom_field_123_present}}
<p>{{request_item_custom_field_123}}</p>
{{/is_request_item_custom_field_123_present}} {{/request_item_context}}

Der bedingte Abschnitt blendet seinen Inhalt aus, wenn für diese Position keine Antwort vorliegt. Verwenden Sie für die Antworten der Teilnehmer is_attendance_custom_field_456_present auf dieselbe Weise. Behalten Sie die oben gezeigten doppelten Klammern bei, damit eingegebene Antworten HTML-escaped werden. Um eine formatierte Zusammenfassung der Buchungs- und Teilnehmerantworten einzufügen, verwenden Sie {{request_item_custom_fields_summary}} innerhalb von request_item_context.

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. Eine erneute Abfrage gibt dasselbe Token zurück; KORONA Event verlängert es, sobald weniger als 12 Stunden seiner Gültigkeit übrig sind.

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