Customer API Entwicklung

Beispielbinding

<binding name="API300Soap" closeTimeout="00:10:00" openTimeout="00:10:00"

receiveTimeout="00:10:00" sendTimeout="00:10:00" allowCookies="false"

bypassProxyOnLocal="false" hostNameComparisonMode="StrongWildcard"

maxBufferPoolSize="2147483647" maxBufferSize="2147483647" maxReceivedMessageSize="2147483647"

textEncoding="utf-8" transferMode="Buffered" useDefaultWebProxy="true"

messageEncoding="Text">

<security mode="Transport" />

</binding>

Beispielcode

string CusToken = "15343D17-****-*****-****-************";

string AuthToken = "5AF7B0AE-****-*****-****-************";

API300.API300SoapClient Service = new API300.API300SoapClient("API300Soap", "https://api.myhypersoft.de/Service/API300.asmx");

API300.APIGeneralResponse Result = Service.ServerDateTime(CusToken, AuthToken);

System.Console.WriteLine("Response: " + Result.Status.ServerDateTime);

Umsatzdaten „Get Revenue“

Über unsere Revenue Schnittstelle, können Sie Artikel und Umsatzdaten über unseren Portalbereich abrufen.

Die Voraussetzung zum Abruf von Umsatzdaten ist eine Enterprise Reports Lizenz pro Standort.

Für die Abfrage von Umsatzinformationen werden gültige CUS und AUTH Token benötigt, welche Sie während der Anbindungsphase durch unsere Entwicklungsabteilung erhalten.

Im Live-Betrieb wird Ihr Unternehmen in unseren Schnittstellen im Portal gelistet, so dass gemeinsame Kunden selbstständig die benötigten Token durch das aktivieren der Schnittstelle erstellen können.

Aktuell werden die Informationen alle 15 Minuten vom POS in unseren Portal geladen. Dieser Wert kann nicht angepasst werden.

Artikel- und Rechnungsinformationen werden ebenfalls auf 15 Minuten gruppiert.

API Dokumentation: https://b2b.myhypersoft.de/APIDoc.aspx

Endpunkt: https://b2b.myhypersoft.de/Service/API300.asmx

Ihnen stehen die folgenden Funktionen zum Datenabruf zur Verfügung:

Funktion Erklärung
GetStations

Über diese Funktion erhalten Sie die Informationen zu den verfügbaren Stationen.

Hiermit werden die aktuellen Daten ohne Historie übergeben.

GetProfitCenter

Über diese Funktion erhalten Sie die Informationen zu den verfügbaren ProfitCentern.

Hiermit werden die aktuellen Daten ohne Historie übergeben.

GetRevenue

Über diese Funktion erhalten Sie die Informationen zu den Buchungen. Der Parameter TtaDate ermittelt für den Tag entsprechende Buchungen. Der FullMonth liefert den vollen Monat. (Es stehen verschiedene Varianten zur Verfügung).

Es können auch die Channel-Informationen per „GetRevenue“ abgefragt werden: CatSubGroup, ChannelName, SubChannelName, DeliveryTypeName

GetExtraRevenue Über diese Funktion erhalten Sie die Informationen zu den gebuchten Extras. Der Parameter TtaDate ermittelt für den Tag entsprechende Extras Buchungen. Der FullMonth liefert den vollen Monat. (Es stehen verschiedene Varianten zur Verfügung)
GetTransactions Über diese Funktion erhalten Sie die Informationen zu den Vorgängen. Der Parameter TtaDate ermittelt für den Tag entsprechende Vorgänge. Der FullMonth liefert den vollen Monat. Die Reihenfolge der Datensätze ist wichtig. Durch das TTA (theoretischer Tagesabschluss) Datum welches z.B. um 6 Uhr ist, sind die Daten der Uhrzeit in dieser Reihenfolge 900, 1000,... 2300, 0, 100, 200 (um 6 Uhr beginnt der neue Tag nicht um 0 Uhr). Für die Uhrzeit ist damit keine aufsteigende Sortierung möglich. Die Reihenfolge in der die Daten ausgegeben werden ist entscheidend. (Es stehen verschiedene Varianten zur Verfügung)
GetPayments Über diese Funktion erhalten Sie die Informationen zu den getätigten Zahlungen.
GetStockTaking Funktionen für den Abruf der Inventur-/Bestandsdaten.

Ergänzende eSolutions Information...

Die API enthält seit 09.2022 auch erweiterte Umsatzdaten, um die Abfrage von Bestelltypen, Subgruppen und Channels. Die Informationen sind innerhalb der API Doku auufgeführt.

3rd-Party-Warenkorb „Set Webshop2 Basket“

Über unsere „3rd-Party-Warenkorb“ Schnittstelle, können Sie vordefinierte Warenkörbe an eine Reservierung anhängen und an unseren Webshop 2.0 übergeben. Die Übergebenen Artikel müssen zuvor über die Funktion „GetWebshop2Articles“ abgerufen worden sein.

Beispielanwendung...

In einem externen System (z.B. einer Homepage, oder einem externen Reservierungssystem) wurden Artikel (In diesem Fall Tickets für eine Schifffahrt) gebucht, welche im Anschluss an unseren Shop zur weiteren Verarbeitung (Bestellprozess, Kundendaten, Payment, Versand von Tickets, Verarbeitung am POS, Übermittlung von Rechnungen) übermittelt werden.

Beispiel Automatisch zustellbares Ticket...

Die Voraussetzung für die Übergabe von Warenkörben ist ein Lizenzierter Webshop 2.0, weitere Lizenzen sind nicht erforderlich. Für die Übergabe von Warenkörben werden gültige CUS und AUTH Token benötigt, welche Sie während der Anbindungsphase durch unsere Entwicklungsabteilung erhalten. Im Live-Betrieb wird Ihr Unternehmen in unseren Schnittstellen im Portal gelistet (falls gewünscht), so dass gemeinsame Kunden selbstständig die benötigten Token durch das aktivieren der Schnittstelle erstellen können.

Einsprung URL...

Der Aufruf eines „3rd-Prty-Warenkorbes“ erfolgt per Einsprungs-URL, welche den vordefinierten Warenkorb aufruft. Hiermit kann der User den Warenkorb auch nicht mehr verändern, dies kann lediglich durch die Fremdanwendung ausgelöst werden. (Der User muss hierfür auf „zurück“ klicken)

Beispiel einer Einsprung URL:

https://demo.myhypersoftapp.de/shop/?lng=de&token=%3dBD1sYpDS3ao%3d&hash=26936fbe5d1bef09e70d1d40d6314368816b14bbc6f52105bc70f3c37cea9d12

Normale URL + Sprache + APIToken + Hashwert

Hinweis: Die Hashwertberechnung ist ein Sicherheitsfeature und wird nicht in unserer Dokumentation aufgeführt.

Hinweis: Die „Einsprung URL“ kann parallel zu einer „normalen“ Shop URL genutzt werden. Die Standardfunktionen und Bestelltypen das Shops werden mittels der normalen URL aufgerufen, während die „3rd-Prty-Warenkorb“ Funktionen über die Einsprung URL aufgerufen werden. User können nicht zwischen diesen beiden Varianten innerhlab eines Bestellvorgangs wechseln.

Hinweis: Wird ein Webshop mittels vordefiniertem Warenkorb per „Einsprung URL“ aufgerufen, so stehen nur noch folgende Funktionen zur Verfügung:

  • Registrieren

  • Einloggen

  • Userbereich

  • Bestellvorgang

  • Zahlung

  • Zurück zur Fremdanwendung

Kundendaten des Warenkorbs...

Für „3rd-Party-Warenkorb“ - Bestellungen werden die Kundendateneinstellungen des Bestelltyps „Web-Gutscheine“ verwendet.

Hinweis: Entgegen des Bestelltyps „Web-Gutscheine“ können „3rd-Party-Warenkörbe“ auch mit der Zahlungsart „Web-Gutscheine“ bezahlt werden, sofern diese aktiviert und eingerichtete wurde.

API und Funktionen

API Dokumentation: https://api.myhypersoft.de/APIDoc.aspx

Ihnen stehen die folgenden Funktionen zum Datenabruf zur Verfügung:

Funktion Erklärung
GetWebshop2Articles

Abrufen der Artikel für eine Kundennummer

Aufbau der Abgerufenen Artikeldaten: https://api.myhypersoft.de/APIDoc.aspx#APIWebshopArticle

GetWebshop2Baskets Abrufen von Warenkörben mehrerer Reservierungen
SetWebshop2Baskets

Warenkörbe von Reservierungen setzen

SetWebshop2BasketPaid

Mit dieser Funktion kann ein Basket auf 'bezahlt' mit einem Paymenttype 45 gesetzt werden. Zusätzlich werden alle Felder der zugehörigen Reservierung mit Beispieldaten gefüllt, so als ob der Basket über den Webshop bezahlt wurde.

Onboarding

Wenn bereits ein Webshop 2.0 vorhanden ist, werden nur die Token und Hashwertberechnung von der Hypersoft-Entwicklung benötigt. Der Shop verbleibt trotz „Einsprung URL“ im Standard.

Alle an den Webshop übergebenen Artikel müssen dem jeweiligen Webshop-Sortiment entsprechen. Zuvor muss mindestens einmal eine erfolgreiche Artikelsynchronisierung mit dem Shop erfolgen.

Webhook erforderlich...

Für die Verwendung des 3rd-Party-Warenkorbens muss zwingend die Webhook-Funktion eingerichtet werden: https://api.myhypersoft.de/APIDoc.aspx#SetReservationsWebhook2

Eine Webhook-Funktion kann ausfallen, weswegen ca. alle 2 Stunden die Funktion „GetReservation2“ auf Änderungen abrufen werden sollte.

API Tickets „Online Tickets“

Alle Ticketartikel, welche über den Webshop 2.0 verkauft werden, werden automatisch zu eSolution Tickets (Online Tickets). Hierfür müssen die Ticket-Artikel die Eigenschaft „Ticket“ im Artikelstamm erhalten. Hierbei ist das Portal das führende System, welches die Ticketnummern vergibt. In diesem Fall erzeugt das Portal zum Zeitpunkt des Verkaufs eine 14-stellige Ticketnummer, welche sich wie folgt zusammensetzt:

49 (Country Code) 95 (Online Ticket) 1234567890 (10 zufallsgenerierte Stellen).

Beispiel: 49 95 1234567890 (Als QR-Code)

Hiermit können 1,7 Millionen Ticketnummern pro Markeninhaber (oder Zentrale) erstellt werden.

Die Voraussetzung ist ein eingerichteter Mastertoken pro Standort.

Einrichtung...

Für die Einrichtung des Ticketsystems muss eine Ticketzentrale definiert werden. Dies ist typischerweise die Kundenummer der Zentrale.

Dies kann aktuell nur durch die Entwicklungsabteilung von Hypersoft definiert werden, erfordert aber KEINE Projektarbeit)

Workflow...

  1. Ticketartikel mit der Eigenschaft „Ticket“ werden über den Webshop 2.0 verkauft.

  2. Das Portal generiert eine 14-Stellige Ticketnummer.

  3. Die Bestellung wird inkl. Ticketnummer an das POS übergeben.

  4. Nach der Bestellung und Verarbeitung am POS erhält der User die bestellten Tickets per Download und Email.

  5. Optional kann mittels NoCOO die Rechnung an den User per E-Mail verschickt werden.

  6. Bei der Einlösung fragt das POS die jeweilige Ticketnummer auf Gültigkeit im Portal ab.

  7. Das Portal gibt die Rückmeldung „Gültig“ oder „nicht gültig“.

  8. War das Ticket gültig, so sendet das POS die Informationen „ist eingelöst“ an das Portal, so dass das Ticket entwertet wird.

Verkaufte Tickets können in der Bestellübersicht im Portal eingesehen und optional heruntergeladen werden:

Einschränkungen und Limitierungen...

Es können aktuell keine Mehrfach-Tickets erzeugt werden, welche beispielsweise 3 x eingelöst werden können.

Es können aktuell keine bestimmten Ticket-Kontingente verwaltet werden, es greift das Standard-Artikelverfügbarkeits-System des Webshops (Ausnahme: Über die Funktion „3rd-Party-Warenkörbe“ kann ein externes System die Verfügbarkeiten sicherstellen).

Kundendaten „Get Customers“

Über unsere „GetCustomers“ Schnittstelle, können Sie Kundendaten über unseren Portalbereich abrufen und bearbeiten.

Die Voraussetzung zum Abruf von Kundendaten ist eine „Kundenstamm 2.0“ Lizenz pro Standort.

Für die Abfrage von Kundendaten werden gültige CUS und AUTH Token benötigt, welche Sie während der Anbindungsphase durch unsere Entwicklungsabteilung erhalten.

Im Live-Betrieb wird Ihr Unternehmen in unseren Schnittstellen im Portal gelistet, so dass gemeinsame Kunden selbstständig die benötigten Token durch das aktivieren der Schnittstelle erstellen können.

Kundendaten können auch im „Webhook“ Verfahren abgeglichen werden, um eine Synchronisierung zwischen zwei System zu ermöglichen.

API Dokumentation: https://api.myhypersoft.de/APIDoc.aspx

Ihnen stehen die folgenden Funktionen zum Datenabruf zur Verfügung:

Funktion Erklärung
GetCustomers2 Über diese Funktion erhalten Sie Kundendatensätze. Die Abfrage wird durch den Parameter ChangesSince auf Datensätze begrenzt, die ab dem übergebenen DateTime-Wert modifiziert wurden. Geben Sie hier den MinValue an erhalten Sie den kompletten Kundenstamm. Mit dem Parameter CustomerTokens können Sie unter Angabe von CusTokens bestimmte Datensätze abfragen.
SetCustomers2 Ändert die übergebenen Kunden. Der Identifizierungstoken gibt an welcher Datensatz geändert wird. Wird kein Identifizierungstoken angegeben, so wird ein neuer Datensatz erzeugt.
GetCustomersWebhook2 Abrufen vom aktuell hinterlegten Webhook für den Kundenstammm.
SetCustomersWebhook2 Speichern/Aktualisieren des Webhooks für den Kundenstamm. Der Webhook wird automatisch ausgelöst, wenn ein Datensatz verändert wird. Daraufhin können die geänderten Daten mit ChangesSince, vom letzten Abruf, abgerufen werden. (Achtung: Bei Änderungen durch diese Schnittstelle wird der Webhook auch ausgelöst.) Der Webhook ist ein POST und erwartet vom Webhookserver ein Status Code 200 'OK' als Bestätigung für das Erfolgreiche verarbeiten. Die Antwort muss innerhalb von 5 Sekunden erfolgen. Es wird empfohlen die information zu speichern, die Antwort zu senden und danach die Verarbeitung zu beginnen. Der Body Content ist ein JSON Objekt '{'Typ': 'Customer2', 'ServerTime': string (Aktuelle Serveruhrzeit im Format ISO 8601) (Optional)[, 'ExtraData': string (Hinterlegte ExtraData)]}'. Der Head vom Webhook enthält Host: {Host}, Content-Type: application/json; charset=utf-8, Content-Length: {Body Content Length}, Connection: Close, Accept: */*, Accept-Encoding: gzip, Expect: 100-continue und optional x-hypersoft-signature: {Signatur Hex-String}.

Reservierung „Get Reservations“

Über unsere „Get Reservations“ Schnittstelle, können Sie Reservierungsinformationen über unseren Portalbereich austauschen.

Die Voraussetzung zum Austausch von Reservierungsdaten ist eine „Reservierung 2.0“ Lizenz pro Standort.

Für den Austausch von Reservierungsinformationen werden gültige CUS und AUTH Token benötigt, welche Sie während der Anbindungsphase durch unsere Entwicklungsabteilung erhalten.

Im Live-Betrieb wird Ihr Unternehmen in unseren Schnittstellen im Portal gelistet, so dass gemeinsame Kunden selbstständig die benötigten Token durch das aktivieren der Schnittstelle erstellen können.

Hinweis: Die Reservierungsinformationen werden alle 30 Sekunden vom POS aus dem Portal abgerufen und zurückgegeben.

API Dokumentation: https://api.myhypersoft.de/APIDoc.aspx

Ihnen stehen die folgenden Funktionen zum Datenabruf zur Verfügung:

Funktion Erklärung
GetReservations2 Gibt Reservierungen zurück. Die Abfrage wird durch den Parameter ChangesSince auf Datensätze begrenzt, die ab dem übergebenen DateTime-Wert modifiziert wurden. Geben Sie hier den MinValue an erhalten Sie alle Reservierungen. Mit dem Parameter ReservationTokens können Sie unter Angabe von ReservationTokens bestimmte Datensätze abfragen.
SetReservations2 Ändert die übergebenen Reservierungen. Der Identifizierungstoken gibt an welcher Datensatz geändert wird. Wird kein Identifizierungstoken angegeben, so wird ein neuer Datensatz erzeugt.
GetReservation2objects Gibt Reservierungsobjekte zurück. Die Abfrage wird durch den Parameter ChangesSince auf Datensätze begrenzt, die ab dem übergebenen DateTime-Wert modifiziert wurden. Geben Sie hier den MinValue an erhalten Sie alle Reservierungsobjekte. Mit dem Parameter ReservationobjectTokens können Sie unter Angabe von ReservationobjectTokens bestimmte Datensätze abfragen.
GetReservationsWebhook2 Abrufen vom aktuell hinterlegten Webhook für die Reservierung.
SetReservationsWebhook2 Speichern/Aktualisieren des Webhooks für die Reservierung. Der Webhook wird automatisch ausgelöst, wenn ein Datensatz verändert wird. Daraufhin können die geänderten Daten mit ChangesSince, vom letzten Abruf, abgerufen werden. (Achtung: Bei Änderungen durch diese Schnittstelle wird der Webhook auch ausgelöst.) Der Webhook ist ein POST und erwartet vom Webhookserver ein Status Code 200 'OK' als Bestätigung für das Erfolgreiche verarbeiten. Die Antwort muss innerhalb von 5 Sekunden erfolgen. Es wird empfohlen die information zuspeichern, die Antwort zu senden und danach die Verarbeitung zu beginnen. Der Body Content ist ein JSON Objekt '{'Typ': 'Reservation2', 'ServerTime': string (Aktuelle Serveruhrzeit im Format ISO 8601) (Optional)[, 'ExtraData': string (Hinterlegte ExtraData)]}'. Der Head vom Webhook enthält Host: {Host}, Content-Type: application/json; charset=utf-8, Content-Length: {Body Content Length}, Connection: Close, Accept: */*, Accept-Encoding: gzip, Expect: 100-continue und optional x-hypersoft-signature: {Signatur Hex-String}.

NoCOO Digitale Rechnungen API

Über unsere „NoCOO“ Schnittstelle, können Sie Vorgangs-, Preis- und Artikelinformationen abrufen.

Die NoCOO-Schnittstelle kann aktuell nur in Verbindung mit der Reservierungs-Schnittstelle verwendet werden.

Die Voraussetzung zum Abruf von Artikelinformationen ist eine NoCOO Lizenz pro Standort.

Für die Abfrage von Artikelinformationen werden gültige CUS und AUTH Token benötigt, welche Sie während der Anbindungsphase durch unsere Entwicklungsabteilung erhalten.

Im Live-Betrieb wird Ihr Unternehmen in unseren Schnittstellen im Portal gelistet, so dass gemeinsame Kunden selbstständig die benötigten Token durch das aktivieren der Schnittstelle erstellen können.

NoCOO-Artikelinformationen stehen erst nach Abschluss des Vorgangs am POS zur Verfügung.

API Dokumentation: https://nocoo.myhypersoft.de/APIDoc.aspx

Endpunkt: https://nocoo.de/Service/API300.asmx

Ihnen stehen die folgenden Funktionen zum Datenabruf zur Verfügung:

Funktion Erklärung
NoCOO Buchungsdaten Vorgangs- und Rechnungsinformationen
GetNoCOOByReservation Liest die NoCOO Daten zu einer Reservierung

 

In den Details stehen Ihnen die folgenden Details pro Vorgang zur Verfügung:

Variable Erklärung
NoCOOCode Der NoCOOCode
HypersoftCustomernumber Hypersoft-Kundennummer
StationNo Stationsnummer
StationName Stationsname
InvoiceNo RechnungsnummerGeschlossen Die Rechungsnummer im Front Office ist wie folgt aufgebaut, um auch dem Notbetrieb gerecht zu werden: Kassennummer (max 3stellig) lfd. Rechnungsnummer (6Stellen) und Formularnummer (-2Stellen). Beispiele: An Kasse 99 die 12345te Rechnung auf dem zweiten Formular: 99123456-02 An Kasse 10 die 5te A5 Rechnung auf dem vierten Formular: 10000005-04 Es gibt also jeweils einen Rechnungsnummernkreis pro Kasse und Formular.
InvoiceDateTime Rechnungszeitpunkt
Canceled Storniert (Status)
Gross Double Gesamt Brutto
OnlineOrderNo Online-Bestellnummer
TableNo Tischnummer (oder allgemeine Vorgangsnummer)
CustomerNo Kundennummer
CustomerToken Kunden ID
CardNo Kartennummer
RoomNo Zimmernummer
ReservationToken Reservierungs ID
PaymentType Zahlungstyp
Channel Channel (der Order Channel)
ChannelTyp ChannelTyp (welcher Art wie 3rd Party, Webshop oder ähnliches)
LastChangeAt Letzter Upload der NoCOO Daten
Items Einzelne Positionen
PDF Rechnungs-PDF

Zurück zur übergeordneten Seite: 3rd Party Kunden, Reservierung, Tickets API