Schnellstart für die Booking API
- Last verified
- Last verified 23. Sept. 2026
In diesem Tutorial verkaufen Sie einen Gutschein über die Booking API und übergeben die Zahlung an die gehostete Zahlungsseite des Shops. Dafür brauchen Sie sechs Anfragen: Gutschein finden, in den Warenkorb legen, Kunden hinzufügen, erforderliche Rechtsdokumente lesen, Checkout abschließen und Zahlung prüfen. Mit denselben Schritten verkaufen Sie auch Tickets; Termine und Zeitfenster mit der Booking API anzeigen zeigt, wie Sie stattdessen Tickets mit Termin in den Warenkorb legen.
Bevor Sie beginnen
- Ein Shop in KORONA Event, der mindestens einen veröffentlichten Gutschein verkauft.
- Die Domain des Shops, zum Beispiel
tickets.example.com, und Ihr KORONA Event API-Host. - Ein Werkzeug, das HTTP-POST-Anfragen mit JSON-Body sendet, zum Beispiel
curloder der HTTP-Client Ihrer Anwendung.
Senden Sie jede Anfrage als POST https://<api-host>/api/graphql/booking/v1 mit diesen Headern:
Content-Type: application/json
X-Tenant-Domain: tickets.example.com
Accept-Language: deDer Body ist ein JSON-Objekt mit query und variables. So funktioniert die Booking API erklärt die Datensätze und Tokens, die unten verwendet werden.
1. Gutschein finden
Listen Sie die Gutscheine des Shops auf. posId: "auto" wählt den eigenen Verkaufskanal des Shops.
query DiscoverVouchers {
offers(posId: "auto", offerableTypes: [VOUCHER_CONFIGURATION], first: 20) {
edges {
node {
... on VoucherConfiguration {
id
nameTranslated
currentPriceValue
}
}
}
}
}{
"data": {
"offers": {
"edges": [
{
"node": {
"id": "2a1dc9d4-fb0b-4dd5-808f-858033098f31",
"nameTranslated": "Geschenkgutschein",
"currentPriceValue": { "amount": 5000, "currency": "EUR" }
}
}
]
}
}
}Geldbeträge enthalten amount in der kleinsten Einheit der Währung; 5000 sind also 50,00 EUR.
2. Gutschein in den Warenkorb legen
Die erste Warenkorb-Mutation ohne requestId legt den Warenkorb an. Speichern Sie das zurückgegebene accessToken: Es ist das Warenkorb-Token für alle weiteren Anfragen.
mutation AddToCart($input: RequestItemCreateInput!) {
requestItemCreate(input: $input) {
request {
accessToken
totalGrossValue
checkoutHold {
expiresAt
secondsRemaining
}
}
requestItem {
id
}
errors {
key
message
messageTranslated
}
}
}{
"input": {
"offerableType": "VOUCHER_CONFIGURATION",
"offerableId": "2a1dc9d4-fb0b-4dd5-808f-858033098f31",
"pricings": [
{
"quantity": 1,
"priceOriginType": "VOUCHER_CONFIGURATION",
"priceOriginId": "2a1dc9d4-fb0b-4dd5-808f-858033098f31"
}
]
}
}Die Antwort enthält das Warenkorb-Token, die Warenkorbsumme und den Checkout-Hold. Um eine weitere Position in denselben Warenkorb zu legen, senden Sie das Warenkorb-Token beim nächsten requestItemCreate als requestId.
3. Kunden hinzufügen
Senden Sie die Daten des Kunden mit dem Warenkorb-Token als id. Fügen Sie eine Rechnungsadresse hinzu und kennzeichnen Sie sie mit billing: true.
mutation AddCustomer($input: RequestUpdateInput!) {
requestUpdate(input: $input) {
request {
contact {
email
}
billingAddress {
city
}
checkoutPolicy {
compatible
targetState
}
requiresShipping
customFieldsCompletion {
allRequiredComplete
}
}
errors {
key
message
messageTranslated
}
}
}{
"input": {
"id": "<cart token>",
"contact": {
"firstName": "Alex",
"lastName": "Example",
"email": "[email protected]",
"customer": {
"addresses": [
{
"billing": true,
"street": "Example Street 1",
"postalCode": "12345",
"city": "Berlin",
"country": "DE"
}
]
}
}
}
}Prüfen Sie den zurückgegebenen Warenkorb vor dem Checkout:
| Feld | Vorgehen |
|---|---|
checkoutPolicy.targetState ist BOOKED | Fahren Sie mit diesem Tutorial fort. |
checkoutPolicy.compatible ist false | Der Warenkorb enthält Angebote, die nicht gemeinsam abgeschlossen werden können. Entfernen Sie die Positionen aus checkoutPolicy.conflicts. |
requiresShipping ist true | Fügen Sie eine Adresse mit shipping: true in einem Land aus shop.allowedShippingCountries hinzu. |
customFieldsCompletion.allRequiredComplete ist false | Starten Sie den Checkout nicht. Die Booking API kann diese Angaben nicht erfassen. Leiten Sie den Kunden zum Kaufabschluss in den gehosteten Shop weiter. |
4. Erforderliche Rechtsdokumente lesen
Kunden müssen den erforderlichen Rechtsdokumenten des Shops zustimmen. Zeigen Sie für jedes Dokument nameTranslated und checkboxLabelTranslated mit einem Kontrollkästchen an und verlinken Sie auf den Dokumenttext aus legalDocument(id:).
query RequiredDocuments {
legalDocuments(required: [true], first: 20) {
edges {
node {
id
nameTranslated
checkboxLabelTranslated
publishedAt
}
}
}
}Speichern Sie für den nächsten Schritt id und publishedAt jedes Dokuments. publishedAt bezeichnet die Version, der der Kunde zugestimmt hat.
5. Checkout abschließen
Nachdem der Kunde den Dokumenten zugestimmt hat, schließen Sie den Checkout ab. Die Antwort enthält die Rechnung und den Link zur gehosteten Zahlungsseite.
mutation CompleteCheckout($input: RequestPaymentInitiateInput!) {
requestPaymentInitiate(input: $input) {
request {
state
}
invoice {
accessToken
paymentState
paymentLink
}
errors {
key
message
messageTranslated
}
}
}{
"input": {
"id": "<cart token>",
"legalDocumentAcceptances": [
{ "legalDocumentId": "1", "legalDocumentVersion": "2026-09-23T19:21:22+00:00" },
{ "legalDocumentId": "2", "legalDocumentVersion": "2026-09-23T19:21:22+00:00" }
]
}
}{
"data": {
"requestPaymentInitiate": {
"request": { "state": "BOOKED" },
"invoice": {
"accessToken": "<invoice token>",
"paymentState": "REQUIRES_PAYMENT",
"paymentLink": "https://tickets.example.com/de/payments/<token>"
},
"errors": null
}
}
}Leiten Sie den Browser des Kunden zu paymentLink weiter. Der Kunde wählt auf der gehosteten Zahlungsseite eine Zahlungsart und bezahlt; die Seite verwendet die Sprache Ihres Accept-Language-Headers.
6. Zahlung prüfen
Lesen Sie die Rechnung mit dem Rechnungs-Token, um die Zahlung zu verfolgen. paymentState wechselt zu PAID, wenn die Zahlung erfolgreich war.
query PaymentStatus($invoiceToken: IdOrNumberOrToken!) {
invoice(id: $invoiceToken) {
paymentState
paymentIntentCreateError
payments {
state
providerInitializationFailed
}
request {
state
checkoutHold {
secondsRemaining
}
ticketsUrl: shareablePublicTicketsUrl(format: PDF)
}
}
}Der Link zu den Tickets kann bereits vorhanden sein, während die Ticketaktivierung noch aussteht. Er kann die gehostete Ticketseite öffnen, auf der die Tickets nach Abschluss der Aktivierung verfügbar sind. Verwenden Sie das Vorhandensein des Links nicht als Signal dafür, dass ein PDF bereitsteht.
Ergebnis prüfen
- Sie haben das Warenkorb-Token aus Schritt 2 gespeichert und in den Schritten 3 und 5 verwendet.
- Der Kunde hat vor Schritt 5 allen erforderlichen Rechtsdokumenten zugestimmt.
- Der Kunde ist über
paymentLinkauf der gehosteten Zahlungsseite gelandet.
