This article is for developers, please find information in the english version below.


Das Amadeus360 Modul OnlineGutscheine hat eine eigene API Schnittstelle, mit der andere Kassensysteme oder Drittanbieter Gutscheine des Amadeus360 Systems verkaufen, prüfen oder einlösen können.

Die folgenden Informationen sind für Entwickler von Drittsystemen geschrieben.


Voraussetzungen



INHALTSVERZEICHNIS

English Version TOC


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.

zurück zum Inhaltsverzeichnis

2. Verbindungstest /IP-Adresse

Die erste Verbindung zur API 'Online-Gutscheine' braucht wegen der Autorisierung mit Nutzername /Passwort im angesprochenen Amadeus360-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 Amadeus360 Service für die Online-Gutscheine.


Function „ping“

URL https://login.amadeus360.de/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

zurück zum Inhaltsverzeichnis

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  https://login.amadeus360.de/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.

zurück zum Inhaltsverzeichnis

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  https://login.amadeus360.de/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
zurück zum Inhaltsverzeichnis

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
 https://login.amadeus360.de/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.

zurück zum Inhaltsverzeichnis

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  https://login.amadeus360.de/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


zurück zum Inhaltsverzeichnis


English Version

1. General

Please note that all requests need to be encrypted using SSL, so please make sure you use https connections.

All requests are HTTP requests, the POST parameters are sent using POST to the servers. The response is a JSON requests – you can find additional information about this format at http://www.json.org/

Please note, that there is a maximum number of failed attempts for requests to prevent attacks. The values are fairly high - but should you get a „DENIED“ message, please wait a bit before you send further requests and check your code for errors.


2. Connection test/ IP Address

The first connection to the Token API requires a one-time authorization using Username / Password of the associated store. Additionally, every connection is encrypted using a pre-shared key and the current IP address of the connecting client.

So it’s necessary to know your current IP address for communicating with the server. No issue for a dedicated server or static ISPs – for users with dynamic IPs you can ask the Token API, which IP connects to you and at the same time check service availability.


Function „ping“

URL https://login.amadeus360.de/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

zurück zum Inhaltsverzeichnis

3. Authentication / Hash-Generation


Every action besides ping and login expects a hash. To generate this hash you have to use the „login“ action, which expects your login name and a certain encrypted password hash.


The password is a MD5 Hash (32 chars), build out of three parameters: MD5 of the API password, your current IP address and the pre-shared key you received when you created the token API key.



Function „login“ [POST]

URL  https://login.amadeus360.de/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


After successful login, you only need the submitted hash for further communication as long as your IP address doesn’t change – in all other cases, you need to generate a new hash using the login function. The generated hash is valid for 2 hours.

zurück zum Inhaltsverzeichnis

4. Tokens

4.1 Validate token („checkcode“)


Using the „checkcode“ function, you can check a valid token. If it’s valid, it’s current remaining value and the expiration date.



Function „checkcode“ [POST]

URL  https://login.amadeus360.de/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


zurück zum Inhaltsverzeichnis

4.2 Redeem token („redeem“)

You can use the Token API to redeem tokens. Please be aware, that because of additional security risks involved, this function requires special token privileges. Please check our documentation for additional details.


Function „redeem“ [POST]
URL
 https://login.amadeus360.de/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


Please keep in mind, that a status of „OK“ only means, that the request has been successfully received by the server – it doesn’t give any details about the actual process of redeeming any amount from the given token. 

To check the actual redeem status, please make sure to check the value in the field „resp“ separately!

zurück zum Inhaltsverzeichnis

4.3 Sell token („purchase“)

You can use the Token API to sell tokens. Please be aware, that because of additional security risks involved, this function requires special token privileges.

Selling a token is done through the same API as cash sales in the backend – meaning the value of the token and the actual billing process has to be handled by the customer directly. For more details about this feature and legal definitions, please check your contract and our online documentation.



Function „purchase“ [POST]

URL  https://login.amadeus360.de/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
zurück zum Inhaltsverzeichnis