So funktioniert die Booking API

Mit der Booking API verkaufen Ihre eigene Website oder App, was ein KORONA Event Shop verkauft: Tickets für Veranstaltungen mit festem Termin und für Zeitfenster, Eintritte, Artikel und Gutscheine. Dieser Artikel erklärt das Modell hinter der API. Der Schnellstart für die Booking API führt durch einen vollständigen Kauf.

Die API ist ein GraphQL-Endpunkt unter /api/graphql/booking/v1 auf Ihrem KORONA Event API-Host. Jede Anfrage bestimmt den Shop über den Header X-Tenant-Domain mit der Domain des Shops. Senden Sie Accept-Language, um Namen, Rechtstexte und Zahlungsseiten in dieser Sprache zu erhalten.

Integrationsstufen

Legen Sie fest, wie viel des Kaufs Ihre Anwendung übernimmt.

Stufe	Ihre Anwendung übernimmt	KORONA Event übernimmt
Gehostete Zahlung (empfohlen)	Angebotsanzeige, Termin- und Zeitauswahl, Warenkorb, Codes, Kundendaten, rechtliche Einwilligungen und Checkout	Auswahl der Zahlungsart, Karten- und Wallet-Zahlungen, 3-D Secure, erneute Zahlungsversuche und Bestätigungsseite
Vollständig headless	Alles oben Genannte und zusätzlich die Zahlung selbst	Zahlungsabwicklung über den angebundenen Zahlungsanbieter

Bei der gehosteten Zahlung schließt Ihre Anwendung den Checkout ab und leitet den Kunden dann zu dem Zahlungslink weiter, den KORONA Event zurückgibt. Der Kunde bezahlt auf der gehosteten Zahlungsseite des Shops, die alle für den Shop eingerichteten Zahlungsarten unterstützt. Die Booking API stellt außerdem paymentIntentCreate für Headless-Integrationen mit Zahlungsanbietern bereit. Dieser Artikel und die Anleitungen beschreiben die gehostete Zahlung. Informationen zu Headless-Zahlungen finden Sie in der generierten API-Referenz und in den Integrationsanforderungen Ihres Zahlungsanbieters.

Das Kaufmodell

Ein Kauf durchläuft vier Datensätze.

Datensatz	API-Typ	Bedeutung
Angebot	`Event`, `EventTemplate`, `Admission`, `Product`, `VoucherConfiguration`	Etwas, das der Shop verkauft. `offers` listet Angebote auf, `offer` liest eines.
Warenkorb	`Request`	Die Bestellung des Kunden, während sie entsteht und nach dem Checkout. Jede Position ist ein `RequestItem`.
Rechnung	`Invoice`	Wird beim Checkout erstellt, wenn etwas zu zahlen ist. Zahlungsversuche gehören zur Rechnung.
Tickets	URL am Warenkorb	`shareablePublicTicketsUrl(format:)` verweist auf die Tickets des Kunden, sobald sie verfügbar sind.

Eine Position im Warenkorb verweist immer auf ein Angebot und enthält eine oder mehrere Preisangaben. Eine Preisangabe ist eine Menge zu einem Preis: Bei Veranstaltungen und Zeitfenstern stammt der Preis aus einer Preisregel (PRICE_RULE), bei Artikeln aus dem Artikel (PRODUCT) und bei Gutscheinen aus der Gutscheinkonfiguration (VOUCHER_CONFIGURATION). Der Server berechnet Preise immer selbst; die Booking API nimmt keine Preise vom Client an.

Tokens

Die Booking API verwendet keinen API-Schlüssel. Den Zugriff auf einen Warenkorb oder eine Rechnung gewährt das jeweilige Token; Kundenkonten haben ein eigenes Token.

Token	Woher Sie es erhalten	Wohin Sie es senden
Warenkorb-Token	`request.accessToken` aus der ersten Warenkorb-Mutation	Als `id` bei `request` und den Warenkorb-Mutationen, oder als `requestId` beim Hinzufügen oder Ändern von Positionen
Rechnungs-Token	`invoice.accessToken` aus `requestPaymentInitiate`	Als `id` bei `invoice`
Anmelde-Token des Kunden	`contact.authToken` aus `contactLogin`	Als `Authorization: Bearer <token>`, nur für Operationen des Kundenkontos

Behandeln Sie Warenkorb- und Rechnungs-Tokens wie Passwörter: Wer das Token hat, kann diesen Warenkorb oder diese Rechnung lesen und ändern. Speichern Sie sie in Ihrer Sitzung und nicht in URLs, die Sie weitergeben. Warenkorb- und Rechnungs-Tokens sind nicht austauschbar.

Eine Anfrage mit Warenkorb- oder Rechnungs-Token darf nur ein Feld auf oberster Ebene abfragen. Um etwa den Warenkorb und die rechtlichen Dokumente zu lesen, senden Sie zwei Anfragen.

Checkout-Zustände

request.checkoutPolicy gibt an, wie der Warenkorb abgeschlossen wird. Lesen Sie das Feld vor dem Checkout.

`targetState`	Was der Checkout bewirkt	Unterstützung in der Booking API
`BOOKED`	Bucht den Warenkorb und erstellt die zu zahlende Rechnung	`requestPaymentInitiate`
`RESERVED`	Reserviert den Warenkorb bis zu einer Frist ohne Zahlung	`requestReserve`
`REQUESTED`	Sendet eine Buchungsanfrage, die Mitarbeitende bestätigen	`requestRequest`

Wenn checkoutPolicy.compatible den Wert false hat, enthält der Warenkorb Angebote, die nicht gemeinsam abgeschlossen werden können. checkoutPolicy.conflicts listet die betroffenen Positionen auf; bitten Sie den Kunden, sie zu entfernen oder getrennt abzuschließen.

Nach einem Checkout mit BOOKED wechselt invoice.paymentState bei erfolgreicher Zahlung von REQUIRES_PAYMENT zu PAID. Eine kostenlose Bestellung gibt sofort eine Rechnung mit PAID zurück, ein vor Ort bezahltes Angebot gar keine Rechnung. Reservierungen und Buchungsanfragen enden ohne Rechnung in RESERVED oder REQUESTED.

Checkout-Hold

Solange ein Kunde einkauft, hält der Warenkorb seine Plätze für eine begrenzte Zeit. request.checkoutHold.expiresAt und secondsRemaining zeigen, wie lange. Endet der Checkout-Hold, storniert KORONA Event den unbezahlten Warenkorb, gibt seine Plätze frei, und weitere Änderungen am Warenkorb schlagen mit einem checkoutHold-Fehler fehl. Zeigen Sie einen Countdown an und legen Sie nach Ablauf einen neuen Warenkorb an.

Fehler

Eine Antwort kann auf HTTP-Ebene erfolgreich sein und trotzdem fehlschlagen. Prüfen Sie zuerst die GraphQL-errors auf oberster Ebene und dann die errors-Liste der Mutation. Mutationsfehler enthalten eine maschinenlesbare message, den betroffenen Eingabe-key und eine übersetzte messageTranslated, die Sie dem Kunden anzeigen können. Fehlercodes der Booking API listet die Codes auf und wie Sie darauf reagieren.

Wiederholen Sie einen Checkout- oder Zahlungsschreibvorgang nicht automatisch, wenn eine Antwort fehlt. Lesen Sie zuerst den Warenkorb oder die Rechnung, um zu sehen, ob der Vorgang erfolgreich war.