INHALTSVERZEICHNIS
1. Einrichten einer neuen Gutscheinschnittstelle in Amadeus360
Zunächst muss dem System die neue Gutscheinschnittstelle bekannt gemacht werden. Die Einstellungen finden sich im eingeloggten Bereich unter Einstellungen / Interface / Externe Dienste / Gutscheinanbieter.
Felder:
Nummer | Die Festgeschriebene Identifikationsnummer für den Gutscheinanbieter (kann nicht geändert werden). |
Name | Die Bezeichnung für den Gutscheinanbieter (kann frei gewählt werden). |
Aktiv | Wenn aktiv, werden API-Abfragen an den Gutscheinanbieter gesendet. |
API-Key | Der API-KEY mit dem sich das Amadeus360 System identifiziert bei API-Anfragen aller art. (muss gewählt werden) |
Redirect-URL | Die URL an die, die API- Anfragen gesendet werden sollen. (muss gewählt werden) |
Finanztyp | Der Finanztyp der in der Kasse für diesen Gutscheinanbieter konfiguriert wurde. (sollte immer gewählt werden) |
2. Endpunkte
Ist ein Gutscheinanbieter angelegt und aktiv geschaltet, werden an folgende Endpunkte Web-Anfragen von Amadeus360 Geschickt.
- Es wird immer eine Antwort vom Typ JSON erwartet.
- Die Antwortzeit sollte nicht länger als drei Sekunden betragen, ansonsten wird die Anfrage abgebrochen.
2.1 Anfragen für Gutschein-Verkauf
Endpunkt:
<REDIRECT-URL>/purchase?api-key=<API-KEY>&amount=<AMOUNT>
GET-Parameter:
api-key | Der für den Gutscheinanbieter definierte API-KEY. |
amount | Die Brutto Höhe und somit das Startguthaben des verkauften Gutscheins. |
Von Amadeus360 erwartete Antwort wenn Anfrage verarbeitet wurde:
{ "token": "Valid", "tokencode": "GUTSCHEINCODE", "wert": 50.00 }
Feldname | JSON-Datentyp | Beschreibung |
token | String | Feld muss den Wert „Valid“ haben wenn der Gutschein angelegt wurde und „Invalid“ wenn der Gutschein nicht angelegt wurde. |
tokencode | String | Der Einzigartige Gutscheincode der soeben für den verkauften Gutschein erzeugt wurde. |
wert | Float | Die Brutto Höhe und somit das Startguthaben des Gutscheinverkaufs. |
Von Amadeus360 erwartete Antwort wenn Anfrage nicht verarbeitet werden konnte:
{ "token": "Invalid", "grund": "Gutschein konnte nicht erzeugt werden weil…" }
Feldname | JSON-Datentyp | Beschreibung |
token | String | Feld muss den Wert „Valid“ haben wenn der Gutschein angelegt wurde und „Invalid“ wenn der Gutscheincode nicht angelegt wurde. |
grund | String | Freitextfeld für den Grund der Ablehnung. |
2.2 Anfragen für Gutschein-Prüfungen
Endpunkt:
<REDIRECT-URL>/checkcode?api-key=<API-KEY>&code=<GUTSCHEINCODE>
GET-Parameter:
api-key | Der für den Gutscheinanbieter definierte API-KEY. |
code | Der zu prüfende Gutscheincode |
Von Amadeus360 erwartete Antwort wenn Anfrage verarbeitet wurde:
{
"token": "Valid",
"tokencode": "GUTSCHEINCODE",
"startwert": 50.00,
"restwert": 12.50
}
Feldname | JSON-Datentyp | Beschreibung |
token | String | Feld muss den Wert „Valid“ haben wenn Gutscheincode bekannt ist oder „Invalid“ wenn der Gutscheincode unbekannt ist. |
tokencode | String | Der soeben überprüfte Gutscheincode in unveränderter Form. |
startwert | Float | Der Ursprüngliche Brutto Gutscheinwert nach Kauf des Gutscheins. |
restwert | Float | Der noch verbleibende Restwerts des Gutschein nach Abzug aller Einlösungen. |
Von Amadeus360 erwartete Antwort wenn Anfrage nicht verarbeitet werden konnte:
{ "token": "Invalid", "grund": "Gutschein konnte nicht angelegt werden weil…" }
Feldname | JSON-Datentyp | Beschreibung |
token | String | Feld muss den Wert „Valid“ haben wenn Gutscheincode bekannt ist oder „Invalid“ wenn der Gutscheincode unbekannt ist. |
grund | String | Freitextfeld für den Grund der Ablehnung. |
2.3 Anfragen für Gutschein-Aufladungen
Endpunkt:
<REDIRECT-URL>/addvalue?api-key=<API-KEY>&code=<GUTSCHEINCODE>&amount=<AMOUNT>
GET-Parameter:
api-key | Der für den Gutscheinanbieter definierte API-KEY. |
code | Der aufzuladende Gutscheincode. |
amount | Die Brutto Höhe der Aufladung um die das Gutschein Saldo erhöht werden soll. |
Von Amadeus360 erwartete Antwort wenn Anfrage verarbeitet wurde:
{ "token": "Valid", "tokencode": "GUTSCHEINCODE", "wert_zuvor": 50.00, "wert_jetzt": 100.00 }
Feldname | JSON-Datentyp | Beschreibung |
token | String | Feld muss den Wert „Valid“ haben wenn der Gutschein aufgeladen wurde und „Invalid“ wenn der Gutschein nicht aufgeladen wurde. |
tokencode | String | Der Gutscheincode der soeben aufgeladen wurde in unveränderter Form. |
wert_zuvor | Float | Die Brutto Höhe des Gutscheinwerts vor der Aufladung. |
wert_jetzt | Float | Die Brutto Höhe des Gutscheinwerts nach der Aufladung. |
Von Amadeus360 erwartete Antwort wenn Anfrage nicht verarbeitet werden konnte:
{ "token": "Invalid", "grund": "Gutschein konnte nicht aufgeladen werden weil…" }
Feldname | JSON-Datentyp | Beschreibung |
token | String | Feld muss den Wert „Valid“ haben wenn der Gutschein aufgeladen wurde und „Invalid“ wenn der Gutschein nicht aufgeladen wurde. |
grund | String | Freitextfeld für den Grund der Ablehnung. |
2.4 Anfragen für Gutschein-Einlösungen
Endpunkt:
<REDIRECT-URL>/redeem?api-key=<API-KEY>&code=<GUTSCHEINCODE>&amount=<AMOUNT>
GET-Parameter:
api-key | Der für den Gutscheinanbieter definierte API-KEY. |
code | Der Gutscheincode auf dem die Einlöse stattfinden soll. |
amount | Die Brutto Höhe des Betrags der eingelöst werden soll. |
Von Amadeus360 erwartete Antwort wenn Anfrage verarbeitet wurde:
{ "token": "Valid", "tokencode": "GUTSCHEINCODE", "wert_zuvor": 100.00, "wert_jetzt": 80.01 }
Feldname | JSON-Datentyp | Beschreibung |
token | String | Feld muss den Wert „Valid“ haben wenn der Gutschein eingelöst werden konnte und „Invalid“ wenn der Gutschein nicht eingelöst wurde. |
tokencode | String | Der Gutscheincode der soeben eingelöst wurde in unveränderter Form. |
wert_zuvor | Float | Die Brutto Höhe des Gutscheinwerts vor der Einlösung. |
wert_jetzt | Float | Die Brutto Höhe des Gutscheinwerts nach der Einlösung. |
Von Amadeus360 erwartete Antwort wenn Anfrage nicht verarbeitet werden konnte:
{ "token": "Invalid", "grund": "Gutschein konnte nicht eingelöst werden weil…" }
Feldname | JSON-Datentyp | Beschreibung |
token | String | Feld muss den Wert „Valid“ haben wenn der Gutschein eingelöst werden konnte und „Invalid“ wenn der Gutschein nicht eingelöst wurde. |
grund | String | Freitextfeld für den Grund der Ablehnung. |
3. Anhang
Es wird empfohlen alle Responses mit folgenden DRAFT 07 JSON-Schema Dateien zu validieren, bevor die Antwort an Amdeus360 getätigt wird.
3.1 Gutschein-Verkauf
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "token" ], "properties": { "token": { "enum": [ "Valid", "Invalid" ] }, "tokencode": { "type": "string", "minLength": 1 }, "wert": { "type": "number", "minimum": -9999999999.99, "maximum": 9999999999.99 }, "grund": { "type": "string", "minLength": 1 } }, "if": { "properties": { "token": { "const": "Valid" } } }, "then": { "required": [ "tokencode", "wert" ] }, "else": { "required": [ "grund" ] } }
3.2 Gutschein-Prüfungen
{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "required": [ "token" ], "properties": { "token": { "enum": [ "Valid", "Invalid" ] }, "tokencode": { "type": "string", "minLength": 1 }, "startwert": { "type": "number", "minimum": -9999999999.99, "maximum": 9999999999.99 }, "restwert": { "type": "number", "minimum": -9999999999.99, "maximum": 9999999999.99 }, "tokengueltig": { "type": "string", "format": "date" }, "tokencomplete": { "type": "boolean" }, "grund": { "type": "string", "minLength": 1 } }, "if": { "properties": { "token": { "const": "Valid" } } }, "then": { "required": [ "tokencode", "startwert" ] }, "else": { "required": [ "grund" ] } }
3.3 Gutschein-Aufladungen
{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "required": [ "token" ], "properties": { "token": { "enum": [ "Valid", "Invalid" ] }, "tokencode": { "type": "string", "minLength": 1 }, "wert_zuvor": { "type": "number", "minimum": -9999999999.99, "maximum": 9999999999.99 }, "wert_jetzt": { "type": "number", "minimum": -9999999999.99, "maximum": 9999999999.99 }, "grund": { "type": "string", "minLength": 1 } }, "if": { "properties": { "token": { "const": "Valid" } } }, "then": { "required": [ "tokencode", "wert_zuvor", "wert_jetzt" ] }, "else": { "required": [ "grund" ] } }
3.4 Gutschein-Einlösungen
{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "required": [ "token" ], "properties": { "token": { "enum": [ "Valid", "Invalid" ] }, "tokencode": { "type": "string", "minLength": 1 }, "wert_zuvor": { "type": "number", "minimum": -9999999999.99, "maximum": 9999999999.99 }, "wert_jetzt": { "type": "number", "minimum": -9999999999.99, "maximum": 9999999999.99 }, "grund": { "type": "string", "minLength": 1 } }, "if": { "properties": { "token": { "const": "Valid" } } }, "then": { "required": [ "tokencode", "wert_zuvor", "wert_jetzt" ] }, "else": { "required": [ "grund" ] } }