Wer nutzt das?

Admin (Ticketsystem und Stripe)

Was wird gezeigt?

Erfahre in diesem Artikel, wie unsere Schnittstelle aufgebaut ist und wofür man diese nutzen kann. 

Was ist eine Schnittstelle und wie funktioniert diese?

Eine Schnittstelle dient in unserem System dazu, Informationen aus dem System heraus automatisiert abzurufen bzw. zu verarbeiten. Die Schnittstelle kann aktuell:
  • Verbindungen nach dem Prinzip SSO herstellen. Mittels der Schnittstelle kann eine Verbindung zwischen Kundenkonten im Ticketsystem und einem externen System hergestellt werden. Dies ist z.B. der Fall wenn man eine eigene App nutzt und Kunden Konten der App gleichzeitig mit den Kundenkonten des Ticketsystems verbinden möchte
  • Informationen zu Bestellungen und Events aus dem System abrufen und diese extern weiterzuverarbeiten. Beispiele:
    • Eventinformationen (Veranstaltungsname, Tag, Ort,...) abrufen und automatisierte Darstellungen (z.B. Eventkalender) auf der Homepage erzeugen.
    • individuelle Eventseiten erzeugen, bei denen jeder Aufführungstermin auf einer eigenen Webseite dargestellt wird
    • Informationen der Tickets(Eventname, Preis, Sitzplatz, QR-Code) in der eigenen App nachbauen und diese im individuellen Design abbilden

Dokumentation How To:

Link zur Dokumentation: Beschreibung der API


UPDATE 01.11.2024:

Abfrage von Ticket-Scan

  • Veranstalter hinterlegt im System eine URL für den Webhook und aktiviert den Trigger "ticket.scanned"
  • Wenn ein Ticket gescannt wurde, sendet der Webhook die TicketID (GUID) an den Endpoint den der Veranstalter definiert hat
  • Die Ticketnutzer Information (Vorname, Nachname, Phone, E-Mail) kann nun über den API-Endpunkt abgerufen werden
  • URL für die Abfrage: https://www.vbotickets.com/api2/orderdetail/ticketuser/{id}




Part 1: SSO Beispiel für die Logik. Linke Seite = externe App / Rechte Seite = Ticketsystem









Part 2: Webhook (Abrufen von Bestell + Eventinformationen)




1. Generierung des VBO API-Key und API-Secret:

Damit die Schnittstelle benutzt werden kann, ist ein individueller API-Key und API-Secret notwendig.

Dieser kann unter Einstellungen -> Erweiterungen -> VBO API Key erzeugt werden

Hinweis: Die Keys müssen nach der Erzeugung direkt gespeichert werden, da diese beim Verlassen des Menü-Punktes aus Sicherheitsgründen ausgeblendet werden. Anschließend kann nur durch Erzeugung eines neuen Schlüssels ein Key wieder sichtbar gemacht werden.

2. Hinterlegung eines Webhook im System

Unter Einstellungen -> Erweiterungen -> Webhooks muss ein Webhook hinterlegt werden und ein passender Trigger ausgewählt werden

3. Hinzufügen der Trigger zum Webhook

Triggertypen

Order.sale - gibt die Order ID einer neuen Bestellung aus
Order.refund - gibt die Information einer stornierten Bestellung aus
Event.created - gibt eine neu erstelltes Event aus
Eventdate.created - gibt einen Eventtag innerhalb eines Events aus
Event.modified - gibt Änderungen eines Events aus
Eventdate.modified - gibt Änderungen eines Eventtages aus
Event.deleted - gibt die Löschung eines Events aus
Eventdate.deleted - gibt die Löschung eines Eventtages aus
Ticket.scanned - gibt die TicketID eines gescannten Tickets aus

-> Wenn ein Trigger angelegt wurde, kann dieser noch eingeschränkt werden. Entweder alle Events oder nur bestimmte Events.

-> Es können beliebig viele Webhooks und Trigger angelegt werden. Man kann also alle Trigger über einen Webhook ausgeben oder verschiedene Webhooks für jeweils einen Trigger hinterlegen.

4. Script im Zielsystem implementieren

-> Webhook Body auslesen

Webhook Types

// Defines values for WebhookWebhookType. const (

WebhookWebhookTypeOrderRefund WebhookWebhookType = "order.refund"

WebhookWebhookTypeOrderSale WebhookWebhookType = "order.sale" )

// OrderRefund defines model for OrderRefund. type OrderRefund struct {

RefundReceiptID int32 `json:"RefundReceiptID"`

UniqueOrderID string `json:"UniqueOrderID"` }

// OrderSale defines model for OrderSale. type OrderSale struct {

SalesReceiptID int32 `json:"RefundReceiptID"`

UniqueOrderID string `json:"UniqueOrderID"` }

// Webhook defines model for Webhook. type Webhook struct {

Payload json.RawMessage `json:"Payload"`
WebhookDate string `json:"WebhookDate"` WebhookType WebhookWebhookType `json:"WebhookType"` WebhookUrl string `json:"WebhookUrl"`
Id string `json:"id"`

}

-> Je nach Typ (z.b. "order.sale" oder "order.refund" den Orders REST Endpoint) mit den entsprechenden Parametern aufrufen. Die REST API GET Requests müssen mit HMAC authorisiert werden.
-> die benötigten Infos aus dem Response auslesen und für den nächsten Step zur Verfügung stellen



Beispiel für REST API GET Request Auth in Golang:

apiKey := "XXXXXXXXX"
apiSecret := "ZZZZZZZZ"
url := "https://www.vbotickets.com/api2/Order/883d9724-b282-4c09-945f-584628021bc9?salesReceiptID=110"

// GET orders hat keinen Payload -> daher wird nur die URL ge-hasht h := hmac.New(sha256.New, []byte(apiSecret))
h.Write([]byte(url))
sha := hex.EncodeToString(h.Sum(nil))

req, _ := http.NewRequest("GET", url, nil) bearer := "Bearer " + apiKey req.Header.Set("Authorization", bearer) req.Header.Set("SecretHash", sha)





Beispiel für einen Response der REST-API:


{
"Status": "Success", "Error": null, "Data": {

"OrderID": 9666545,
"UserID": 0,
"OrderIDAlt": 0,
"OrderIDParent": 0,
"PromoterID": 8206,
"OrderDate": "2022-06-13T12:35:36.423", "LocaleID": 1031,

"TimeZone": 1,
"SalesMethod": "ONLINE",
"PaymentType": null,
"ShippingType": "eTicket",
"ShippingInfo": "Print your tickets now. You must print a separate ticket for each seat you

purchased. Do not bring this order confirmation. The order confirmation is NOT YOUR TICKET”, "IsPreAuth": false,
"UniqueOrderID": "0aa455e8-2bf6-4c2d-bc4d-bf45cbe152ab",
"LastWarning": null,

"WarningLevel": 0, "Account": {

"AcctID": 3667267, "FirstName": "Rico", "LastName": "Bärisch", "Company": "1", "Title": null,

"Suffix": null, "Salutation": null, "Address": {

"Address1": "Herweghstrasse 4", "Address2": null,
"City": "Dresden", "StateProvince": null,

"ZipCode": "01157",

"Country": "Deutschland" },
"Phone": "",
"MobilePhone": null,
"EmailAddress": rico@egocentric-systems.de, "IsNewsletter": false,

"Birthdate": null }, "BillingAddress": {

"Address1": "Herweghstrasse 4", "Address2": null,
"City": "Dresden", "StateProvince": null,

"ZipCode": "01157",

"Country": "Deutschland" }, "ShippingAddress": null, "OrderPayments": [

{
"OrderPayID": 6172013,
"UserID": 0,
"PaymentDate": "2022-06-13T12:35:33.967", "Total": 120.0,

"CashReceived": 0.0,

"PaymentMethod": "CCTYPE",

"PaymentType": "CreditCard",

"CardType": "VISA",

"NameOnCard": "Rico Bärisch",

"CreditCard": "4242",

"ExpMonth": "4",

"ExpYear": "2024",

"TransactionID": "ch_3LAJ2wJgy8HpGVYJ0RIO1Mim",

"TransactionStart": "2022-06-13T12:35:36.313",

"TransactionEnd": "2022-06-13T12:35:36.313",

"TransactionStatus": "Completed",

"SalesReceiptID": 107,

"RefundReceiptID": 0,

"SalesMethod": "ONLINE",

"UniquePayID": "8d2092e9-faac-4bba-a300-1ce7bf0ef6e5",

"CreditDate": null,

"CreditAmount": 0.0,

"CreditTransactionID": null,

"CreditUserID": 0,

"IsPreAuth": false,

"PreAuthCaptureDate": null,

"BalanceDueDate": null,

"BalancePaid": 0.0,

"LocalisedPaymentType": "VISA" }

],

"OrderDetails": [

{

"OrderDtlID": 19365261,

"EventID": 62710,

"EventDateID": 284246,

"ItemID": 1379465,

"DateCreated": "2022-06-13T12:35:36.343",

"AuditDate": "2022-06-13T12:35:36.343",

"ItemName": "General Admission - Normalpreis",

"ItemDescription": "Null Euro<br>Die, 14. Jun, 2022 @ 0:00 Uhr - Section: Block B -

Normalpreis",

"ItemCat": "ga",

"Qty": 1,

"ListPrice": 40.0,

"Price": 40.0,

"PriceAdjusted": 0.0,

"ServiceFee": 0.0,

"ServiceFeePromoter": 60.0,

"FacilityFee": 0.0,

"Total": 40.0,

"ShippingFee": 0.0,

"OrderFee": 0.0, "TaxRate": 19.0,

"TaxRateBase": 19.00,

"SubPrice": 0.0,

"Option1": "",

"Value1": "",

"Option2": "RegType",

"Value2": "UserInfoForm",

"Option3": "",

"Value3": "",

"TicketUserInfo": "",

"TicketID": "6bdc197b-027c-4dca-8892-1472b9afdcc3", "SalesReceiptID": 107,
"RefundReceiptID": 0,
"SalesReceiptPrefix": "",

"RefundReceiptPrefix": null, "OpenSeat": {

"OpenSeatID": 1379465, "Section": "Block B", "Name": "Normalpreis", "Color": "",

"Picture": "21971_seat.png",
"Notes": "Der Block B befindet sich auf der Nordseite der EnergieVerbund Arena

Dresden.",
"IsVideo": false },

"Seat": null, "EventDate": {

"EventID": 62710, "EventDateID": 284246, "EventDateName": "Null Euro", "Date": "2022-06-14T00:00:00", "Venue": {

"VenueID": 5039,
"VenueName": "EnergieVerbund Arena Dresden (Test)", "VenuePhone": "",
"VenueEmail": "",
"Address": {

"Address1": "Magdeburger Str. 10", "Address2": null,
"City": "Dresden",
"StateProvince": "Sachsen", "ZipCode": "01067 ",

"Country": "Deutschland" } }

},
"Barcode": "O-BJ2BX-G-TKEH-63BQ",
"ItemTax": 6.3865546218487394957983193277, "ServiceFeeTax": 0.0,
"ShippingFeeTax": 0.0,
"OrderFeeTax": 0.0,
"FacilityFeeTax": 0.0,
"Tax": 6.3865546218487394957983193277 },

{
"OrderDtlID": 19365262,
"EventID": 62710,
"EventDateID": 284246,
"ItemID": 1379465,
"DateCreated": "2022-06-13T12:35:36.343",
"AuditDate": "2022-06-13T12:35:36.343",
"ItemName": "General Admission - Normalpreis",
"ItemDescription": "Null Euro<br>Die, 14. Jun, 2022 @ 0:00 Uhr - Section: Block B -

Normalpreis", "ItemCat": "ga",

"Qty": 1,
"ListPrice": 40.0,
"Price": 40.0, "PriceAdjusted": 0.0, "ServiceFee": 0.0, "ServiceFeePromoter": 60.0,

"FacilityFee": 0.0,
"Total": 40.0, "ShippingFee": 0.0, "OrderFee": 0.0, "TaxRate": 19.0, "TaxRateBase": 19.00, "SubPrice": 0.0, "Option1": "",
"Value1": "",
"Option2": "RegType", "Value2": "UserInfoForm", "Option3": "",

"Value3": "",
"TicketUserInfo": "",
"TicketID": "5a4303ec-c2ac-41ed-98a0-225ff1c94eb4", "SalesReceiptID": 107,
"RefundReceiptID": 0,
"SalesReceiptPrefix": "",
"RefundReceiptPrefix": null,
"OpenSeat": {

"OpenSeatID": 1379465, "Section": "Block B", "Name": "Normalpreis", "Color": "",

"Picture": "21971_seat.png",
"Notes": "Der Block B befindet sich auf der Nordseite der EnergieVerbund Arena

Dresden.",
"IsVideo": false },

"Seat": null, "EventDate": {

"EventID": 62710, "EventDateID": 284246, "EventDateName": "Null Euro", "Date": "2022-06-14T00:00:00", "Venue": {

"VenueID": 5039,
"VenueName": "EnergieVerbund Arena Dresden (Test)", "VenuePhone": "",
"VenueEmail": "",
"Address": {

"Address1": "Magdeburger Str. 10", "Address2": null,
"City": "Dresden",
"StateProvince": "Sachsen", "ZipCode": "01067 ",

"Country": "Deutschland" } }

},
"Barcode": "O-BJ2BY-G-TKEH-63BQ",
"ItemTax": 6.3865546218487394957983193277, "ServiceFeeTax": 0.0,
"ShippingFeeTax": 0.0,
"OrderFeeTax": 0.0,
"FacilityFeeTax": 0.0,
"Tax": 6.3865546218487394957983193277 },

{
"OrderDtlID": 19365263, "EventID": 62710,

"EventDateID": 284246,
"ItemID": 1379465,
"DateCreated": "2022-06-13T12:35:36.343",
"AuditDate": "2022-06-13T12:35:36.343",
"ItemName": "General Admission - Normalpreis",
"ItemDescription": "Null Euro<br>Die, 14. Jun, 2022 @ 0:00 Uhr - Section: Block B -

Normalpreis", "ItemCat": "ga",

"Qty": 1,
"ListPrice": 40.0,
"Price": 40.0,
"PriceAdjusted": 0.0,
"ServiceFee": 0.0,
"ServiceFeePromoter": 60.0,
"FacilityFee": 0.0,
"Total": 40.0,
"ShippingFee": 0.0,
"OrderFee": 0.0,
"TaxRate": 19.0,
"TaxRateBase": 19.00,
"SubPrice": 0.0,
"Option1": "",
"Value1": "",
"Option2": "RegType",
"Value2": "UserInfoForm",
"Option3": "",
"Value3": "",
"TicketUserInfo": "",
"TicketID": "f4661271-2fd1-4141-980f-47d48d3816bb", "SalesReceiptID": 107,
"RefundReceiptID": 0,
"SalesReceiptPrefix": "",
"RefundReceiptPrefix": null,
"OpenSeat": {

"OpenSeatID": 1379465, "Section": "Block B", "Name": "Normalpreis", "Color": "",

"Picture": "21971_seat.png",
"Notes": "Der Block B befindet sich auf der Nordseite der EnergieVerbund Arena

Dresden.",
"IsVideo": false },

"Seat": null, "EventDate": {

"EventID": 62710, "EventDateID": 284246, "EventDateName": "Null Euro", "Date": "2022-06-14T00:00:00", "Venue": {

"VenueID": 5039,
"VenueName": "EnergieVerbund Arena Dresden (Test)", "VenuePhone": "",
"VenueEmail": "",
"Address": {

"Address1": "Magdeburger Str. 10", "Address2": null,
"City": "Dresden",
"StateProvince": "Sachsen",

"ZipCode": "01067 ",

"Country": "Deutschland" }

}

},

"Barcode": "O-BJ2BZ-G-TKEH-63BQ",

"ItemTax": 6.3865546218487394957983193277,

"ServiceFeeTax": 0.0,

"ShippingFeeTax": 0.0,

"OrderFeeTax": 0.0,

"FacilityFeeTax": 0.0,

"Tax": 6.3865546218487394957983193277 }

],

"OrderReceipt": {

"OrderReceiptID": 1932005,

"ReceiptID": 107,

"DateStart": "2022-06-13T12:35:36.343",

"DateEnd": "2022-06-13T12:35:36.343",

"ReceiptPrefix": "",

"CashRegisterSignature": null },

"Total": 120.0,

"Shipping": 0.0,

"ServiceFees": 0.0,

"FacilityFees": 0.0,

"OrderFees": 0.0,

"SubTotal": 120.0,

"CashReceived": 0.0,

"CashTotal": 0.0,

"CashChange": 0.0,

"Tax": 19.159663865546218487394957983,

"NetAmount": 100.84033613445378151260504202,

"OpenBalance": 0.0,

"OrderDateLocal": "2022-06-13T21:35:36.423",

"BalanceDueDate": null,

"TicketCount": 3 }

}