Anbieter verschiedener Gutscheinsysteme können sich einfach über die generische Schnittstelle für Gutscheinsysteme integrieren. Vier einfache Aufrufe der Kasse werden vom Anbieter passend und definiert beantwortet, so dass keine speziellen Anpassungen in Amadeus360 notwendig sind.
INHALTSVERZEICHNIS
| Voraussetzungen | |
|---|---|
| Lizenz für Gutscheine | Amadeus360 Modul "Online Gutscheine" |
| Konfiguration "Online Gutscheine" | Einrichtung der Online-Gutscheine am server und in der Kasse Online-Gutschein-System mit Kasse verknüpfen |
| Konfiguration Schnittstelle | Den Anbieter Ger Gutscheine unter "Gutscheinanbieter" eingetragen und aktiv setzen. |
Wird ein Anbieter unter "Gutscheinanbieter" eingetragen und aktiv gesetzt sind nur noch diese Funktionen der Schnittstelle verfügbar. Es können keine Online Gutscheine mehr verkauft oder eingelöst werden.
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.
Wichtig beim Eintragen der Daten ist das kein Leerzeichen am Anfang oder Ende im API-Key oder der Redirect-URL hinterlegt ist.
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" ] } }