Das LINA Modul OnlineGutscheine hat eine eigene API Schnittstelle, mit der andere Kassensysteme oder Drittanbieter Gutscheine des LINA Systems verkaufen, prüfen oder einlösen können.
LINA Data API geändert (alte URL amadeus360 noch erreichbar) LINA Data URL changed to https://api.lina.de/ ...
1. Allgemeines, bitte beachten
Aus Sicherheitsgründen müssen alle Aufrufe SSL-verschlüsselt sein, daher nutzen Sie bitte HTTPS Verbindungen
Alle Aufrufe sind HTTP(s), daher müssen POST-Parameter mit POST zum Server gesandt werden. Antworten sind immer JSON Pakete, zusätzliche Informationen finden Sie auf http://www.json.org/ .
Ebenfalls aus Sicherheitsgründen gibt es eine Höchstzahl fehlgeschlagener Aufrufe pro Zeit. Bekommen Sie eine Antwort "DENIED", warten Sie bitte mit weiteren Aufrufen und prüfen den Code auf Fehler.
2. Verbindungstest /IP-Adresse
Die erste Verbindung zur API 'Online-Gutscheine' braucht wegen der Autorisierung mit Nutzername /Passwort im angesprochenen LINA-Laden einige Zeit.. Zusätzlich wird jede Verbindung mit einem pre-shared-key und der aktuellen IP-Adresse des anfragenden Clients (ihr PC/Server) verschlüsselt. Bei Clients mit dynamisch wechselnden IP-Adressen nutzen sie die API selbst, um die IP ihres Clients abzufragen. So prüfen Sie gleichzeitig die Verfügbarkeit des LINA Service für die Online-Gutscheine.
Function „ping“
URL .../extern/tokenapi/ping
Response „ping“ Fields status "OK" Server is online "Maintenance" We are undergoing maintenance, please see our status page
myip xxx.xxx.xxx.xxx Your current IPv4 address
3. Authentifizierung / Generierung Hash
Jeder Funktionsaufruf außer "ping" und "login" verlangt einen Hash. Zur Generierung dieses Hash müssen sie einen login ausführen, der wiederum den login-Namen und einen verschlüsselten Hash verlangt. Dieser besteht aus dem MD5 des API-Passwortes, der aktuellen IPv4 Adresse des Clients und den pre-shared-key, den sie bekommen haben, als sie den API-key für die API "Online-Gutscheine" erstellt haben.
Function „login“ [POST]
URL .../extern/tokenapi/login
Parameters
username [String] Username for the API user
password [String] md5 ( md5 (Password) + IP-Address + Pre-Shared Key )
Resonse „login“
Codes 200 Request successful 400 Error during request Fields
status "OK" Request successful
"error" Requested failed, see "response" for reason
response Upon error, the textual error message
hash Upon success, the generated hash (40 chars)
laden The name of the store you logged into
ladenid Internal ID for the store you logged into
Nach dem erfolgreichen login benötigen sie nur noch den neu erhaltenen hash, solange sich ihre IP-Adresse nicht ändert. In allen anderen Fällen, müssen sie sich neu anmelden und einen hash generieren. Dieser ist für 2 Stunden gültig.
4. Gutscheine
4.1 Gutschein validieren ("checkcode")
Mit der "Checkcode" Funktion prüfen sie die Gültigkeit eines Gutscheins zu validieren, den aktuellen Restwert und das Ablaufdatum abzufragen.
Function „checkcode“ [POST]
URL .../extern/tokenapi/checkcode
Parameters
hash [String] Hash from previous login request
code [String] The token code to check
Response „checkcode“
Codes 200 Request successful 400 Error during request Fields
status "OK" Request successful "error" Requested failed, see "response" for reason
response Upon error, contains the exact error text
token "Valid" The supplied Token code is valid
"Invalid" Token code is invalid
tokencode The (nicely) formatted token code startwert Original token value in €
restwert Remaining token value in €
tokengueltig Date until when the token is valid
Format dd.mm.yyyy
tokencomplete Can the token be redeemed in parts of completly
0 = You can redeem parts
1 = You can only redeem the complete value
4.2 Gutschein einlösen ("redeem")
Mit der Funktion "redeem" lösen sie Gutscheine ein. Wegen besonderer Sicherheitsrisiken, werden hierfür spezielle Berechtigungen im Gutschein-System benötigt. Bitte prüfen Sie die Dokumentation für weitere Details.
Function „redeem“ [POST]
URL
.../extern/tokenapi/redeem
Parameters
hash [String] Hash from previous login request
code The code for the token to be redeemed
amount [Float] Value you want to redeem from the token.
Response „redeem“
Codes 200 Request successful 400 Error during request Fields
status "OK" Request successful "error" Requested failed, see "response" for reason
response Upon error, contains the exact error text
token "Valid" The supplied Token code is valid
"Invalid" Token code is invalid
resp "OK" Amount has been redeemed "Err" Error trying to redeem, see „msg“
msg Error description from "resp" as string amount_old Value of the token before redeeming amount_new Value of the token after redeeming
Der Status "OK" bedeutet nur, dass die Anfrage erfolgreich beim Server empfangen wurde - er gibt keine Information über den laufenden Prozess der Einlösung oder Reduzierung von angefragten Gutschein.
Um diesen zu prüfen, werten sie bitte "resp" gesondert aus.
4.3 Gutschein verkaufen ("purchase")
Mit der Funktion "purchase" verkaufen sie Gutscheine. Wegen besonderer Sicherheitsrisiken, werden hierfür spezielle Berechtigungen im Gutschein-System benötigt. Bitte prüfen Sie die Dokumentation für weitere Details.
Der Verkauf eines Gutscheins löst im Backend den gleichen Prozess aus wie der persönliche Verkauf eines Gutscheins. Der Wert und der Bezahlvorgang müssen durch den Kunden selbst vorgenommen werden. Für weitere Details du den rechtlichen Vorschriften prüfen sie bitte ihren Vertrag und die Dokumentation.
Function „purchase“ [POST]
URL .../extern/tokenapi/purchase
Parameters
hash [String] Hash from previous login request
amount [Float] Value of token to be created
sendmail [String] An email address, where the token should be sent – this value is optional
tokens [String] The hash of the template to be used – you can find this in your Token backend
layout [Integer] The layout ID to be used for this token. Make sure this layout is assigned to the tokens ID from above in your backend. This value is optional
tokenfrom [String] From whom this token is (only for layout > 0)
tokenfor [String] For whom this token is (only for layout > 0)
Response „purchase“
Codes 200 Request successful 400 Error during request Fields
status "OK" Request successful "error" Requested failed, see "response" for reason
response Upon error, contains the exact error text
code The token code for the created token
amount Value for the created token
qrcode Base64-decoded string of the token code
layouthttp http-link to the generated token, if layout > 0