Zum Inhalt springen

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 curl oder der HTTP-Client Ihrer Anwendung.

Senden Sie jede Anfrage als POST https://<api-host>/api/graphql/booking/v1 mit diesen Headern:

http 
Content-Type: application/json
X-Tenant-Domain: tickets.example.com
Accept-Language: de

Der 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.

graphql 
query DiscoverVouchers {
  offers(posId: "auto", offerableTypes: [VOUCHER_CONFIGURATION], first: 20) {
    edges {
      node {
        ... on VoucherConfiguration {
          id
          nameTranslated
          currentPriceValue
        }
      }
    }
  }
}
json 
{
  "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.

graphql 
mutation AddToCart($input: RequestItemCreateInput!) {
  requestItemCreate(input: $input) {
    request {
      accessToken
      totalGrossValue
      checkoutHold {
        expiresAt
        secondsRemaining
      }
    }
    requestItem {
      id
    }
    errors {
      key
      message
      messageTranslated
    }
  }
}
json 
{
  "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.

graphql 
mutation AddCustomer($input: RequestUpdateInput!) {
  requestUpdate(input: $input) {
    request {
      contact {
        email
      }
      billingAddress {
        city
      }
      checkoutPolicy {
        compatible
        targetState
      }
      requiresShipping
      customFieldsCompletion {
        allRequiredComplete
      }
    }
    errors {
      key
      message
      messageTranslated
    }
  }
}
json 
{
  "input": {
    "id": "<cart token>",
    "contact": {
      "firstName": "Alex",
      "lastName": "Example",
      "email": "alex@example.com",
      "customer": {
        "addresses": [
          {
            "billing": true,
            "street": "Example Street 1",
            "postalCode": "12345",
            "city": "Berlin",
            "country": "DE"
          }
        ]
      }
    }
  }
}

Prüfen Sie den zurückgegebenen Warenkorb vor dem Checkout:

FeldVorgehen
checkoutPolicy.targetState ist BOOKEDFahren Sie mit diesem Tutorial fort.
checkoutPolicy.compatible ist falseDer Warenkorb enthält Angebote, die nicht gemeinsam abgeschlossen werden können. Entfernen Sie die Positionen aus checkoutPolicy.conflicts.
requiresShipping ist trueFügen Sie eine Adresse mit shipping: true in einem Land aus shop.allowedShippingCountries hinzu.
customFieldsCompletion.allRequiredComplete ist falseStarten 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:).

graphql 
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.

graphql 
mutation CompleteCheckout($input: RequestPaymentInitiateInput!) {
  requestPaymentInitiate(input: $input) {
    request {
      state
    }
    invoice {
      accessToken
      paymentState
      paymentLink
    }
    errors {
      key
      message
      messageTranslated
    }
  }
}
json 
{
  "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" }
    ]
  }
}
json 
{
  "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.

graphql 
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 paymentLink auf der gehosteten Zahlungsseite gelandet.

Verwandte Artikel