Buchungen mit Zahlung an einen externen Partner erstellen
- Availability
- Beta
- Last verified
- Last verified 17. Nov. 2026
Verwenden Sie diesen Server-zu-Server-Ablauf, wenn ein externes Buchungssystem die Zahlung vom Gast entgegennimmt und später mit der Veranstaltungsstätte abrechnet. KORONA Event erstellt die Buchung und einen fiskalischen Lieferschein für den konfigurierten Wiederverkäufer. Die Veranstaltungsstätte setzt ihren vereinbarten Abrechnungsprozess in KORONA.studio fort.
Bevor Sie beginnen
Beantragen Sie die API-Basis-URL, die Mandantendomäne, den API-Schlüssel des Dienstkontos, die ID des Verkaufspunkts (POS) und die bestehende ID des Vorgangskanals beim Integrationsadministrator des Veranstaltungsortes. Verwenden Sie, sofern verfügbar, einen bestehenden Testmandanten. Bewahren Sie API-Schlüssel auf Ihrem Server auf und halten Sie sie aus Browser-Bundles, Protokollen und Beispielen fern.
Der Administrator muss die Lieferscheine aktivieren und die Integrationszeile des Vorgangskanals für Ihr Dienstkonto konfigurieren, einschließlich des Wiederverkäufer-Ansprechpartners/Kunden und dessen Zuordnung zum KORONA.studio-Kunden. Der unten angegebene Gastkontakt ist von diesem Rechnungskunden getrennt. Die Zuordnung wird bei der Erstellung des Vorgangs gespeichert; spätere Konfigurationsänderungen führen nicht dazu, dass bestehende Vorgänge einem anderen Wiederverkäufer zugeordnet werden.
Die aktuelle Rolle des Dienstkontos benötigt Berechtigungen zum Erstellen, Lesen und Aktualisieren von Vorgängen sowie Leseberechtigungen für die Felder „Angebot“, „Preis“, „Position“ und „Kontakt“, die im Beispiel verwendet werden. Für Stornierungen wird ebenfalls die Berechtigung zum Aktualisieren von Vorgängen benötigt. Hierbei handelt es sich um gewöhnliche Rollenberechtigungen, nicht um einen auf eigene Integrationsvorgänge beschränkten Zugriff. Siehe Dienstkonto erstellen.
Senden Sie jeden Vorgang als separaten HTTPS-POST-Aufruf an /api/graphql/booking/v1:
Content-Type: application/json
Authorization: Bearer <service-account API key>
X-Tenant-Domain: <tenant domain>
Accept-Language: deVerwenden Sie einen JSON-Body, der query und variables enthält. Geben Sie bei jedem Aufruf den API-Schlüssel an, auch bei Aufrufen, bei denen das zurückgegebene Warenkorb-Token verwendet wird. Ein Warenkorb-Token allein gewährt keine Zahlungsberechtigung für Partner. Anmeldedaten für die Management-API werden von diesem Endpunkt nicht akzeptiert.
Verwenden Sie denselben konfigurierten Wert für posId für die Ermittlung, die Preisangabe und die Erstellung. Ein explizit festgelegter POS hat Vorrang vor automatischen Standardwerten. Bei der automatischen Erstellung hat die POS-Überschreibung durch den Kanal bzw. den Benutzer Vorrang vor dem Standard-POS des Benutzers, gefolgt vom Standardwert des Kanals. Der explizit festgelegte POS in diesem Beispiel verhindert, dass beim Abrufen der Preise und beim Erstellen des Vorgangs unterschiedliche Kontexte zum Tragen kommen. Die Vorgangskanäle und der POS sind Konfigurationsparameter und keine Berechtigungszuweisungen.
Angebote und Besuchszeiten abrufen
query PartnerOffers($posId: ID!, $after: String) {
offers(posId: $posId, offerableTypes: [EVENT_TEMPLATE], first: 50, after: $after) {
edges {
node {
... on EventTemplate {
id
nameTranslated
timeZone
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}Geben Sie für die ausgewählte Eventvorlage einen begrenzten Datumsbereich und die gewünschte Anzahl an:
query PartnerSlots($id: ID!, $posId: ID!, $span: TsRange!, $quantity: Int!, $after: String) {
offer(type: EVENT_TEMPLATE, id: $id, posId: $posId) {
... on EventTemplate {
potentialEvents(posId: $posId, span: $span, spanOperator: CONTAINS_START, quantity: $quantity, first: 50, after: $after) {
edges {
node {
span
remainingQuota
priceRules(posId: $posId) {
id
minPax
maxPax
priceCategory {
id
nameTranslated
}
product {
currentPriceValue
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
}Übergeben Sie einen halboffenen Bereich, zum Beispiel [2026-12-01T00:00:00+01:00,2026-12-02T00:00:00+01:00). Verwenden Sie bei der Erstellung des jeweiligen Elements den Wert von span jedes zurückgegebenen Slots unverändert. Zeigen Sie Zeiten in der IANA-Zeitzone timeZone des Angebots an; fügen Sie keinen festen Zeitzonen-Offset selbst hinzu. Setzen Sie die Paginierung mit endCursor fort, solange hasNextPage wahr ist.
Lesen Sie die Preise aus den Preisregeln des ausgewählten Eintrags aus. „Money“ ist ein JSON-Skalar wie beispielsweise {"amount": 2500, "currency": "EUR"}: Der Betrag wird in der kleinsten Währungseinheit angegeben (hier 25,00 €). Preise und Kapazitäten können sich ändern; die Abfrage reserviert keine Plätze und legt den Endpreis nicht fest. Kampagnenpreise oder spezielle Kontingente müssen separat konfiguriert und vereinbart werden und lassen sich nicht aus diesem API-Ablauf ableiten. Siehe Daten und Uhrzeiten.
Vorgang erstellen
mutation PartnerCreate($input: RequestCreateInput!) {
requestCreate(input: $input) {
request {
id
accessToken
number
externalRef
paymentMethod
state
totalGrossValue
requestItems {
id
offerableId
offerableType
offerableSpan
pricings {
id
quantity
priceValue
}
}
}
errors {
key
message
messageTranslated
}
}
}{
"input": {
"posId": "<configured POS ID>",
"requestChannel": { "id": "<configured order-channel ID>" },
"paymentMethod": "DELIVERY_NOTE",
"externalRef": "PARTNER-ORDER-123",
"idempotencyKey": "create-PARTNER-ORDER-123",
"contact": {
"firstName": "Alex",
"lastName": "Example",
"email": "guest@example.com",
"customer": {}
},
"requestItems": [
{
"offerableType": "EVENT_TEMPLATE",
"offerableId": "<selected template ID>",
"offerableSpan": "<returned slot span>",
"pricings": [{ "priceOriginType": "PRICE_RULE", "priceOriginId": "<returned price-rule ID>", "quantity": 1 }]
}
]
}
}Setzen Sie externalRef auf die Vorgangsnummer des externen Systems. Dies ist die Referenz, anhand derer die Mitarbeiter die beiden Systeme miteinander abgleichen, und sie wird als Vermerk auf dem fiskalischen Lieferschein angegeben. Sie ist von der KORONA Event-Vorgangsnummer (number), externalId und einem Idempotenzschlüssel zu unterscheiden. Für diesen Partnerablauf ist sie erforderlich, auf 200 Byte begrenzt und innerhalb des Mandanten und des Dienstkontos eindeutig, einschließlich stornierter Vorgänge. Verwenden Sie für eine Ersatzbuchung eine neue externe Vorgangsnummer.
Geben Sie für die Erstellung einen idempotencyKey mit einer Länge von höchstens 200 Byte an. Speichern Sie diesen sowie die übermittelte Nutzlast vor dem Absenden. Die Wiederholung desselben Schlüssels mit derselben Eingabe liefert denselben Vorgang und dessen aktuellen Status zurück; bei Änderung der Eingabe wird idempotencyKey: conflict zurückgegeben. Ein anderer Schlüssel mit einer bereits vorhandenen externen Vorgangsnummer gibt externalRef: conflict zurück. Schlüssel und Referenzen bleiben bei der API-Schlüsselrotation für dasselbe Dienstkonto erhalten. Ein neues Dienstkonto verfügt über einen separaten Namensraum.
Bewahren Sie die zurückgegebenen Elemente id, number und accessToken sicher auf. Überprüfen Sie die zurückgegebenen Preise und den Gesamtbetrag vor der Bestätigung. Beim Erstellen eines zeitgesteuerten Vorlagenelements kann ein EVENT-Element mit einer neuen Ereignis-ID zurückgegeben werden; verwenden Sie die zurückgegebene Element-ID für nachfolgende Änderungen.
Bitte geben Sie die erforderlichen Teilnehmer- und Personalisierungsdaten ein und füllen Sie alle erforderlichen Formulare aus, bevor Sie die Buchung bestätigen. Dieses Minimalbeispiel geht von einem Angebot ohne zusätzliche Pflichtfragen aus. Informationen zum unterstützten Erfassungsablauf finden Sie unter Buchungs- und Teilnehmerdaten erfassen.
Ohne erneute Zahlung durch den Gast bestätigen
mutation PartnerConfirm($input: RequestFinalizeInput!) {
requestFinalize(input: $input) {
request {
id
number
state
externalRef
paymentMethod
paymentState
shareablePublicTicketsUrl(format: PDF)
}
invoice {
number
}
errors {
key
message
messageTranslated
}
}
}{
"input": {
"id": "<returned cart accessToken>",
"paymentMethod": "DELIVERY_NOTE",
"idempotencyKey": "confirm-PARTNER-ORDER-123-v1",
"expectedTotalGrossValue": { "amount": 2372, "currency": "EUR" }
}
}Setzen Sie expectedTotalGrossValue auf den von Ihnen akzeptierten Gesamtbetrag unter Verwendung kleinerer Währungseinheiten (2372 bedeutet 23,72 EUR). Die Bestätigung erfolgt unter Anwendung der Preisregeln der Buchungsmaschine und prüft die Kapazität, die Gültigkeitsdauer des Entwurfs sowie die erforderlichen Formulare. Für lokale Entwurfspreise gelten die Preisregeln des bestehenden Buchungsablaufs; eine bloße Bearbeitung des Katalogpreises überschreibt keinen bestehenden Entwurf. Preisänderungen seitens des Anbieters und Bearbeitungen des Entwurfs können den Gesamtbetrag ändern. Ein geänderter Gesamtbetrag gibt expectedTotalGrossValue: stale zurück; aktualisieren Sie die Angebotspreise und holen Sie die Zustimmung ein, bevor Sie den akzeptierten Gesamtbetrag mit einem neuen Bestätigungsschlüssel übermitteln.
Speichern Sie einen Bestätigungsschlüssel und dessen Eingabe vor dem Absenden. Versuchen Sie es bei unklaren Antworten erneut mit demselben Schlüssel und derselben Eingabe. Die Wiederverwendung dieses Schlüssels mit geänderter Eingabe führt zu idempotencyKey: conflict. Ein gespeicherter Validierungsfehler wird für diesen Schlüssel erneut zurückgegeben; verwenden Sie nach Behebung des Problems einen neuen Schlüssel. Bei erfolgreicher Wiederholung wird derselbe Vorgang in seinem aktuellen Status zurückgegeben, ohne dass ein weiterer Lieferschein erstellt wird.
Eine erfolgreiche Bestätigung des Lieferscheins gibt state: BOOKED zurück, und es wird keine neue Rechnung für die Zahlung durch den Gast erstellt. Es wird der fiskalische Lieferschein für die Wiederverkäufer-Zuordnung erstellt. Rufen Sie nicht paymentIntentCreate auf, eröffnen Sie keine gehostete Zahlung und verwenden Sie nicht den Zahlungsanbieter BOOKING_KIT, um Gelder darzustellen, die Ihr System eingezogen hat.
paymentState kann weiterhin REQUIRES_PAYMENT bleiben: Die Zahlung des Gastes an den Partner bedeutet nicht, dass die Veranstaltungsstätte die Abrechnung des Partners erhalten hat. Bitte stützen Sie sich nicht allein auf diesen Status, um zu entscheiden, ob diese Buchung mit Lieferschein bestätigt ist oder ob die Tickets ausgehändigt werden dürfen.
Verwenden Sie die zurückgegebene Ticket-URL unverändert, sofern vorhanden; behandeln Sie diese als Zugangsdaten. Falls diese fehlt, rufen Sie den Vorgang nach der Ticketausstellung erneut ab. Erstellen Sie keinen weiteren Vorgang, um einen Ticket-Link zu erhalten. Die Ticketausgabe hängt von der Ticketkonfiguration des Veranstaltungsortes ab, und ein Link allein stellt keine Bestätigung der Auszahlung durch den Partner dar.
Die Ticketaktivierung und die PDF-Erstellung können asynchron abgeschlossen werden. Wenn der Download HTTP 503 mit Retry-After zurückgibt, warten Sie das angegebene Intervall ab und rufen Sie dieselbe URL erneut auf.
Kunden-E-Mails und Anhänge auswählen
Übergeben Sie email in RequestFinalizeInput oder RequestCancelInput, um die Kunden-E-Mail für diese Aktion zu steuern. Verwenden Sie "email": { "sendEmail": false }, wenn Ihre Integration eigene Kundennachrichten versendet. Setzen Sie diese Option sowohl bei der Bestätigung als auch bei der Stornierung, wenn beide Nachrichten unterdrückt werden sollen. Sie ist keine dauerhafte Einstellung für den Vorgang. Verwenden Sie bei einer Wiederholung der Bestätigung dieselben E-Mail-Einstellungen.
{
"email": {
"sendEmail": true,
"includeTickets": false,
"includeInvoices": false,
"includeVouchers": false,
"includeIcals": false,
"includeOfferableAttachments": false
}
}| Feld | Wirkung bei false |
|---|---|
sendEmail | Unterdrückt die Kunden-E-Mail für diese Aktion einschließlich einer späteren Ticket-E-Mail. Die Buchung wird trotzdem bestätigt und die Tickets werden vorbereitet. |
includeTickets | Schließt Ticket-PDFs, Wallet-Pässe und den standardmäßigen Ticket-Download-Link aus, einschließlich einer späteren Ticket-E-Mail. |
includeInvoices | Schließt Rechnungs-PDFs aus. |
includeVouchers | Schließt Gutschein-PDFs aus. |
includeIcals | Schließt Kalenderanhänge (.ics) aus. |
includeOfferableAttachments | Schließt zusätzliche Dateien aus, die für das Event oder Angebot konfiguriert sind. |
Alle sechs Optionen haben standardmäßig den Wert true, wenn sie weggelassen werden. Sie erlauben die üblichen E-Mails und Anhänge für die Aktion; sie erzwingen keine E-Mail ohne Empfänger und erstellen keine Dokumente. Stornierungs-E-Mails folgen den üblichen Benachrichtigungsregeln der Veranstaltungsstätte und liefern keine nutzbaren stornierten Tickets. Die E-Mail geht mit der konfigurierten Vorlage der Veranstaltungsstätte an den Gastkontakt des Vorgangs. Unabhängige Benachrichtigungen an Mitarbeiter und Ressourcen werden durch diese Optionen nicht gesteuert.
Im Lieferscheinablauf dieser Anleitung erstellt die Bestätigung keine Rechnung für den Gast. Daher hängt includeInvoices: true auch keine solche Rechnung an. Fiskalische Lieferscheine sind keine Anhänge von Kunden-E-Mails. Bei Tickets gilt außerdem die Einstellung der Veranstaltungsstätte für Anhänge oder Download-Links; includeTickets: false schließt beides aus.
Ergebnis nach einer unklaren Antwort prüfen
query PartnerStatus($id: IdOrNumberOrToken!) {
request(id: $id) {
id
number
state
externalRef
paymentMethod
paymentState
totalGrossValue
shareablePublicTicketsUrl(format: PDF)
}
}Verwenden Sie das gespeicherte Warenkorb-Token als id zusammen mit dem API-Schlüssel-Header. Sollte eine Antwort auf die Erstellung verloren gehen, bevor Sie eine Kennung erhalten haben, stellen Sie den Vorgang anhand ihrer externen Vorgangsnummer wieder her:
query PartnerRecover($externalRef: String!) {
bookingByExternalReference(externalRef: $externalRef) {
id
accessToken
number
state
externalRef
totalGrossValue
shareablePublicTicketsUrl(format: PDF)
}
}Diese Abfrage zur Wiederherstellung steht allen authentifizierten Booking-API-Clients zur Verfügung, auch ohne Wiederverkäuferzuordnung oder Zahlung per Lieferschein. Sie durchsucht ausschließlich den aktuellen Mandanten und das aktuelle Dienstkonto, einschließlich stornierter Vorgänge. Die aktuellen Leseberechtigungen und Ressourceneinschränkungen des Kontos gelten weiterhin. Ohne passenden Vorgang gibt sie null zurück. Ein Null-Ergebnis während eines laufenden Aufrufs beweist keinen Fehlschlag: Wiederholen Sie requestCreate mit dem ursprünglichen Erstellungsschlüssel und unveränderten Eingaben. Die Wiederholung per Erstellungsschlüssel erfolgt über diese Mutation; die Suche akzeptiert nur externalRef.
Behalten Sie beim Wechsel des API-Schlüssels dieselbe Dienstkontoidentität bei. Die externe Referenz bleibt dem Vorgang dieses Kontos zugeordnet, auch nach einer Stornierung. Ein anderer Erstellungsschlüssel mit derselben Referenz führt zu einem Konflikt. Auch ohne Erstellungsschlüssel angelegte Vorgänge lassen sich über ihre externe Referenz finden; die Suche bestätigt nicht, dass geänderte Erstellungseingaben eine gültige Wiederholung wären.
Nach Ablauf des Bestätigungs-Timeouts versuchen Sie es erneut mit dem entsprechenden Schlüssel und geben Sie den Vorgang ein oder lesen Sie ihn ein. Verwenden Sie ein Ergebnis vom Typ BOOKED; erstellen Sie keinen Ersatz, um Tickets wiederherzustellen. Ein Ergebnis vom Typ CANCELED bleibt auch bei der Wiederholung eines zuvor erfolgreichen Vorgangs als storniert gelten.
Überprüfen Sie HTTP-Fehler, die oberste Ebene von GraphQL errors und die Mutation-Payload errors. Ein HTTP-Status 200 allein bedeutet noch keinen Erfolg. Bei nicht verfügbarer Kapazität oder geänderten Preisen aktualisieren Sie die Auswahl und holen Sie die Zustimmung des Kunden zu etwaigen Änderungen ein. Bei einem Autorisierungsfehler überprüfen Sie die konfigurierten Zugriffsrechte mit dem Administrator; wechseln Sie nicht in den anonymen Zugriff. Sind Lieferscheine nicht verfügbar, beheben Sie die Probleme bei der Standortkonfiguration, anstatt auf eine andere Zahlungsart auszuweichen.
Eine Buchung stornieren
mutation PartnerCancel($input: RequestCancelInput!) {
requestCancel(input: $input) {
request {
id
state
externalRef
}
errors {
key
message
messageTranslated
}
}
}{ "input": { "id": "<returned cart accessToken>", "autoRefund": false } }Bei einem Vorgang, der ausschließlich über buchhalterische Lieferscheine abgewickelt wurde, wird bei einer Stornierung ein Korrekturlieferschein erstellt. Ihr System ist weiterhin für die Erstattung an den Gast verantwortlich. Senden Sie autoRefund: false; die API lehnt automatische Erstattungen an den Gast für diesen Ablauf ab. Eine wiederholte Stornierung führt nicht zur Erstellung eines weiteren Korrekturlieferscheins.
Bearbeiten Sie Buchungspositionen und Daten der Teilnehmer, solange sich den Vorgang noch im Entwurfsstatus befindet. Die POS-Nummer, die Zahlungsart auf dem Lieferschein und die externe Vorgangsnummer sind nach der Erstellung festgeschrieben. Um eine bestätigte Buchung zu ändern, stornieren Sie diese und erstellen Sie eine Ersatzbuchung mit einer neuen externen Vorgangsnummer und einem neuen Erstellungsschlüssel. Die Verfügbarkeit wird erneut geprüft; durch die Stornierung wird keine Kapazität für die Ersatzbuchung reserviert. Vereinbaren Sie etwaige Stornierungsgebühren und die Erstattungsrichtlinien für Gäste mit dem Veranstaltungsort, bevor Sie diesen Vorgang durchführen.