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 GutscheineAmadeus360 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 - maximal 40 Zeichen).

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"
     ]
   }
 }