Wer? | Admin (Ticketsystem und Stripe) |
Was? | Wie sind unsere Schnittstellen aufgebaut und wofür kann man diese nutzen? |
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
UPDATES START
UPDATE 13.11.2024:
Abfrage einer Eventliste(JSON)
- über einen Link könnt ihr alle Veranstaltungen abrufen
- bei Veranstaltungen im Bereich freie Platzwahl werden die noch verfügbaren Tickets ausgegeben. (Bei Veranstaltungen mit Sitzplätzen wird ein Platzhalter Wert ausgegeben, der nicht der tatsächlichen Menge entspricht)
- Der Link beinhaltet euren API-KEY. Diesen findet ihr unter Einstellungen / Erweiterungen / VBO Api-Key
- Den Key im Beispiel durch euren eigenen ersetzen
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}
UPDATES ENDE
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 }
}
Abschluss & Zusammenfassung
- Erläuterung der API-Grundlagen und Anwendungsmöglichkeiten bei egocentric Systems.
- Beschreibung von Funktionen wie Kundenkontenverbindung, Bestellungs- und Eventinformationen sowie Webhooks für Ereignisbenachrichtigungen.
Deine Antwort nicht gefunden? Schick uns Deine Frage