Die gastroToken API ist ein zusätzliches Produkt in der gastroToken Produktwelt. 

Falls Sie Interesse haben, dieses zusätzlich zu Ihrem vorhandenen gastroToken Vertrag zu nutzen, setzen Sie sich bitte mit unserem Vertrieb in Verbindung.


INHALTSVERZEICHNIS


Allgemeines


Bitte beachten Sie, dass alle Anfragen mit SSL verschlüsselt werden müssen - hierfür benutzen Sie also bitte eine https Verbindung.

Alle Anfragen sind standardisierte HTTP Anfragen, die Parameter werden mittels POST im Header des Requests zum Server transportiert. 

Die Antworten sind JSON formatierte Strings - Sie können weitere Informationen hierüber unter 

http://www.json.org/ finden.


Bitte beachten Sie: Es gibt eine maximale Anzahl an fehlerhaften Anfragen, nach welcher weitere Anfragen für einen kurzen Zeitraum blockiert werden.

Die Werte sind ausreichend hoch für normale Tests eingestellt, aber sollten Sie im Status IHrer Anfrage "DENIED" erhalten, warten Sie bitte einige Minuten bevor Sie weitere Anfragen schicken und überprüfen Sie Code nach Fehlern. 



Verbindungstest / IP Adresse


Bei der ersten Verbindung zur gastroToken API ist eine einmalige Autorisierung mittels Benutzername / Passwort nötig, um die Anfragen dem jeweiligen Laden zuzuordnen. 

Zusätzlich wird jede Verbindung mit einem Hash, bestehend aus einem Pre-Shared Key und der aktuellen IP Adresse des Client-PCs verschlüsselt, um Angriffe zusätzlich zu erschweren.

Daher ist es notwendig, die aktuelle öffentliche IP Adresse des Clients zu kennen. 

Bei statischen IPs oder dedizierten Servern stellt dies kein Problem dar - arbeiten Sie allerdings mit dynamischen IPs, können Sie die gastroToken API abfragen, mit welcher öffentlichen IP Anfragen beim Server eingehen und gleichzeitig die Verfügbarkeit des Servers abfragen.
 

Funktion „ping“

urlhttps://www.gastrotoken.de/ext/ping

Response „ping“

status"OK" - Server ist online
"Maintanance" - Wartungsarbeiten
myip[String] xxx.xxx.xxx.xxx - Ihre aktuelle öffentliche IP Adresse



Authentifizierung / Hash-Erzeugung


Jede Aktion außer Ping und Log-in benötigt einen vorher mit dem Server ausgehandelten Hash.

Um diesen Hash zu erzeugen, müssen Sie die Log-in Action mit Benutzername und einem generierten Passwort aufrufen. 


Die Anmeldedaten erhalten Sie vorab von unserem Vertrieb. 


 

Das Passwort für den Log-in ist ein MD5 codierter Hash (32 Zeichen), welche aus drei Parametern besteht: 

  • MD5 des Account-Passworts
  • IP Adresse des Clients 
  • Pre-Shared Key, welchen Sie ebenfalls vorab erhalten haben.

 

Funktion „login“ – POST Parameter

urlhttps://www.gastrotoken.de/ext/login
username [String], gastroToken Benutzername wie im Anschreiben angegeben
password md5 [ md5[Password] +IP-Adress+ Pre-Shared Key ]

Rückgabe-Parameter „login“

status[String]
"OK" - Anfrage erfolgreich
"error" - Fehler, für weitere Details siehe "response"
response[String] Enthält weiterführende Informationen falls status gleich "error"
hash[String] Bei Erfolg, der generierte Hash (40 Zeichen lang)
laden[String] Der Name des authentifizierten Ladens
ladenid[Int] Die interne ID des Ladens

 

Nachdem der Log-in erfolgreich war, muss für die weitere Kommunikation nur noch der in der Antwort übermittelte Hash verwendet werden, so lange sich die IP Adresse des Client nicht ändert - falls doch, senden spätere Funktionsaufrufe den Status "error" und es muss ein neuer Log-in durchgeführt werden. 


Bitte beachten Sie: Jeder generierte Hash ist für maximal 2 Stunden gültig.



Gutschein validieren ("checkcode")

Mit Hilfe der "checkcode" Funktion kann ein existierender Gutschein überprüft werden und genauere Daten zum Gutschein abgerufen werden.

 

Funktion „checkcode“ – POST Parameter

urlhttps://www.gastrotoken.de/ext/login
hash[String] Der beim Login ausgehandelte Hash-Code
code[String] Der gastroToken Gutscheincode, welcher überprüft werden soll

Rückgabe-Parameter „checkcode“

status[String]
"OK" - Anfrage erfolgreich
"error" - Fehler, für weitere Details siehe "response"
response[String] Enthält weiterführende Informationen falls status gleich "error"
token[String]
"Valid" - Der angegebene Code ist gültig
"Invalid" - Der angegebene Gutschein konnte nicht gefunden werden oder ist für den authentifizierten Laden nicht verfügbar
tokencode[String] Der Gutscheincode (im Format xxxx-xxxx-xxxx-xxxx)
restwert[Double] Der auf dem Gutschein verbleibende Restwert
tokengueltig[String] Datum bis wann der Gutschein gültig ist im Format dd.mm.yyyy
tokencomplete[Int] Ist dieser Wert 1, kann der verbleibende Gutscheinwert nur komplett abgebucht werden. In allen anderen Fällen ist eine Teilabbuchung möglich.

 


Gutschein einlösen ("redeem")


Mit der "redeem" Funktion können vorhandene Gutscheine eingelöst werden. 

Es wird dringend empfohlen, den Gutscheincode mit Hilfe der "checkcode" Funktion vorab zu überprüfen.


Bitte beachten Sie, dass zu häufige Aufrufe dieser Funktion mit falschen codes zu einer temporären Sperre des Zugangs führen kann.


Funktion „redeem“ – POST Parameter

urlhttps://www.gastrotoken.de/ext/redeem
hash[String] Der beim Login ausgehandelte Hash-Code
code[String] Der gastroToken Gutscheincode, welcher eingelöst werden soll
amount[Double] 999.99 - Der € - Wert welcher eingelöst werden soll

Rückgabe-Parameter „redeem“

status[String]
"OK" - Anfrage erfolgreich
"error" - Fehler, für weitere Details siehe "response"
response[String] Enthält weiterführende Informationen falls status gleich "error"
token[String]
"Valid" - Der angegebene Code ist gültig
"Invalid" - Der angegebene Gutschein konnte nicht gefunden werden oder ist für den authentifizierten Laden nicht verfügbar
resp[String]
"OK" - Der gewünschte Betrag wurde vom angegebenen Gutschein abgebucht
"Err" - Es gab einen Fehler beim abbuchen, siehe "msg"
msg[String] Fehlerbeschreibung, falls "resp" den Wert "Err" zurückgegeben hat


Bitte beachten Sie, dass ein Status "OK" nur bedeutet, dass die Anfrage vom Server erfolgreich empfangen wurde und der übermittelte Hash-Code in Ordnung ist.

Er signalisiert nicht, dass die eigentliche Anfrage erfolgreich war. 

Hierfür überprüfen Sie bitte zusätzlich den Wert "resp" .



Gutschein verkaufen ("purchase")

Sie können die gastroToken API auch benutzen, um Gutscheine zu verkaufen. 

Dieser Vorgang basiert auf der gleichen Logik wie die Barverkäufe im gastroToken Kundenbereich.

Das bedeutet, dass der Wert des Gutscheins nicht durch die Gastro-MIS GmbH oder ihre Partner garantiert wird, sondern durch den ausstellenden Betrieb selbst. 

Im Falle eines Ausfalls z. B. durch Insolvenz oder Betriebsaufgabe obliegt es daher exklusiv dem Kunden den Wert gegenüber dem Endkunden auszugleichen. 


Es gibt grundsätzlich zwei Möglichkeiten, die "purchase" Funktion zu verwenden. 

  • Sie können entweder einen Gutscheincode plus QR-Code erstellen und diesen über ein eigenes System dann auf Gutscheine drucken. 


  • Sie wählen ein vorhandenes Layout aus Ihrem gastroToken Kundenbereich, übermitteln dessen Layout ID an die     Schnittstelle und erhalten einen Link, unter welchem Sie das fertige Layout herunterladen können.

            Dieses Layout kann zusätzlich auch direkt an den Kunden gesendet werden.


Funktion „purchase“ – POST Parameter

urlhttps://www.gastrotoken.de/ext/purchase
hash[String] Der beim Login ausgehandelte Hash-Code
amount[Double] 999.99 - Der € - Wert welcher eingelöst werden soll
sendmail[String] Optional, die E-Mail Adresse an welcher der Gutschein gesendet werden soll
tokens[String] Der Hash der zu verwendenden Gutscheinvorlage - Sie finden diesen Wert in Ihrem gastroToken Kundenbereich, es ist der letzte Teil der iFrame URL
layout[Int] Optional, die Layout ID für den Gutschein, falls ein Gutschein erstellt werden soll. Bitte beachten Sie, dass das Layout für den Gutschein-Hash ("tokens") freigeschalten sein muss.
tokenfrom[String] Nur wenn layout > 0, der auf dem Gutschein zu druckende "Von" - Wert
tokenfor[String] Nur wenn layout > 0, der auf dem Gutschein zu druckende "Für" - Wert

Rückgabe-Parameter „purchase“

status[String]
"OK" - Anfrage erfolgreich
"error" - Fehler, für weitere Details siehe "response"
response[String] Enthält weiterführende Informationen falls status gleich "error"
code[String] Gutscheincode des erstellten Gutscheins
amount[Double] Der Wert des erstellten Gutscheins
qrcode[String] Base64-codierter QR-Code des Gutscheincodes
layouthttp[String] HTTPS-Link zum Gutschein, nur wenn layout > 0