TYRIOS eCash – Kassenintegration leicht gemacht

Das eCash-System bietet ein einfach zu bedienendes Terminal, das von jedem teilnehmenden Unternehmen genutzt werden kann, um Benutzer zu suchen und anzulegen und gleichzeitig Transaktionen für den Verkauf von Produkten und Gutscheinen zu erstellen. Die separate Nutzung des Terminals ist jedoch zeitaufwändig und führt zu einem unintegrierten Prozess. Die Integration des eCash-Systems in die eigene Kassensoftware beschleunigt daher nicht nur die Nutzung des Systems, sondern reduziert auch fehlerhafte Dateneingaben, integriert die eCash-Abwicklung in den eigenen Kundenbearbeitungsprozess und verbessert so das gesamte Marketingpotenzial des Gesamtsystems.

Es gibt drei Hauptkategorien, in die ein Kassensystem das TYRIOS eCash System integrieren kann. Die Mindestanforderung ist die Integration der Transaktionsgenerierung (Punkt 2)

1. die Benutzerverwaltung
   1. benutzersuche nach Benutzer-Hash
   2. benutzersuche nach Abfrage
   3. benutzererstellung
2. erstellung von Transaktionen
   1. erstellung von Verkaufstransaktionen mit angegebenem Benutzer (durch Benutzersuche, Benutzersuche oder Benutzererstellung)
   2. anlegen einer Verkaufstransaktion ohne angegebenen Benutzer, aber mit Gutscheincode
   3. anlegen einer Verkaufstransaktion mit angegebenem Benutzer UND Gutscheincode
   4. gutscheintransaktion zum Verkauf eines Gutscheins ohne bestimmten Benutzer
   5. gutscheintransaktion für den Verkauf eines Gutscheins mit angegebenem Benutzer
3. transaktionsübersicht

Es ist möglich, die Anfragen im eCash-Terminal zu untersuchen, da das Terminal die gleichen API-Anfragen verwendet. Ein Testsystem und ein Testkonto können von der Entwicklung angefordert werden.

Version

Authentifizierung

Das TYRIOS eCash-System bietet eine RESTfull API-Schnittstelle, mit der du interagieren kannst. Das Schnittstellenformat ist JSON und UTF-8 kodiert. Der allgemeine Endpunkt lautet:

https://[instance]/service/BonusPointManagement

Für alle Interaktionen mit dem eCash-System sind gültige Anmeldedaten erforderlich. Die Zugangsdaten sind benutzerspezifisch, so dass es möglich ist, dass mehrere Benutzer Zugang zu den eCash-Schnittstellen haben. Die Benutzer werden durch die Unternehmenseinstellungen zugeordnet und sind nicht Teil dieser Integrationsdokumentation.

Die Benutzeranmeldedaten müssen als BASIC AUTHENTICATION angegeben werden.

Grundlegende eCash-Behandlung

Immer wenn ein Benutzer etwas kaufen möchte, erstellt das TYRIOS eCash-System eine Transaktion. Es gibt keinen Geldtransfer ohne eine entsprechende Transaktion. Jedes Unternehmen hat eine Transaktionsübersicht, in der alle das Unternehmen betreffenden Transaktionen aufgelistet sind. Die Integration des eCash-Systems in ein Kassensystem erfordert daher die Erstellung einer Transaktion.

TYRIOS eCash unterstützt zwei verschiedene Möglichkeiten, Artikel innerhalb einer Transaktion zu kaufen

1. durch die Verwendung von Coupons, die durch einen eindeutigen Coupon-Hash identifiziert werden
2. durch die Verwendung eines Benutzerkontos, das durch einen eindeutigen Benutzeridentifikations-Hash identifiziert wird.

Beide Ansätze können kombiniert werden.

Benutzerkonto-Verwaltung

Jeder Benutzer in TYRIOS eCash hat ein eigenes Benutzerkonto mit Punkten, die auf dem Benutzerkonto gespeichert sind. Jeder Punkt entspricht 1 Cent. Ähnlich wie bei Unternehmen hat jeder Nutzer seine Transaktionsübersicht, in der alle Transaktionen mit dem Nutzerkonto aufgelistet sind. Eine zentrale Funktion für die Erstellung einer Transaktion ist es daher, einen Nutzer identifizieren zu können.

Benutzer werden mit einem eindeutigen, nicht erratbaren Benutzer-Hash identifiziert. Dieser Benutzer-Hash wird in der Regel vom Kunden als Barcode (CODE-128 verschlüsselt) mit seinem Mobiltelefon oder einer Plastikkarte angegeben. Für jeden Nutzer kann das System folgende Daten bereitstellen:

• vorname
• nachname
• geburtsdatum (falls angegeben)
• profilbild (falls vorhanden)
• aktuelle Punkte
• eMail-Adresse (falls angegeben)

Die eMail-Adresse ist nicht für alle Nutzer verfügbar, sondern nur für die Nutzer mit Zugang zum Online-Portal / zur App. Vor allem ältere Nutzer haben möglicherweise nur den Nutzer-Hash zur Identifizierung.

Die Benutzerverwaltung kann optional in das Kassensystem integriert werden. Sie ist nicht notwendig. Die Integration der Benutzerverwaltung ermöglicht jedoch die folgenden Anwendungsfälle:

• Du kannst deine Kundendaten auf dem neuesten Stand halten.
• Du kannst die Erlaubnis für den Versand von Kunden-Newslettern einholen.
• Du kannst deine Kundendaten mit relevanten Verkaufsstatistiken anreichern.
• Es ist möglich, dem Kunden seinen aktuellen Punktestand im eCash-System mitzuteilen. Das ist vor allem für ältere Generationen wertvoll, die nicht die Web- oder App-Oberfläche nutzen, um ihre Transaktionen zu überprüfen.
• Es ist möglich, nach Kunden zu suchen. Das ist wertvoll, wenn der Kunde seine Kundenkarte / sein Handy vergessen hat und somit nicht in der Lage ist, den Kundenhash mitzuteilen. Du kannst nach einem Kunden über Vor- und Nachname suchen. (Bitte beachte, dass in diesem Zusammenhang der Benutzer anhand seines Passes validiert werden sollte).
• Es ist möglich, neue Benutzer für das eCash-System anzulegen und dem Benutzer seine individuelle Kundenkarte zu geben. So akzeptiert dein Unternehmen nicht nur eCash, sondern bietet auch die Möglichkeit, sich für das gesamte System zu registrieren.

Benutzersuche nach Hash

Das typischste Verfahren ist die Suche nach Benutzerdaten anhand des Benutzer-Hashs. Der Benutzer-Hash ist eine eindeutige Buchstabenkombination mit genau 15 Zeichen. Du musst den folgenden GET-Endpunkt aufrufen

https://[instance]/BonusPointManagement/UserData/[userHash]

Wenn der Benutzer gültig ist, erhältst du das UserData-Objekt, das folgende Felder enthält:

• die 4 letzten Ziffern des eindeutigen Benutzer-Hashs.
• die Benutzerkennung
• den Vornamen (preName)
• den Nachnamen (Name)
• die E-Mail-Adresse (falls angegeben)
• die Anzahl der aktuellen Punkte
• den Geburtstag (falls angegeben, als Unix-Zeitstempel inkl. Mikrosekunden)

Das Antwortformat der Anfrage ist:

{
  "id": 1, // automatisch vergebene ID des Nutzers
  "preName": "Max", // Vorname
  "name": "Mustermann", // Nachname
  "eMail": "max.mustermann@repalogic.com", // E-Mail-Adresse
  "currentBonusPoints": 213, // aktuelle Bonuspunkte des Nutzers
  "uniqueUserHashPart": "WXYC", // eindeutiger, nutzerspezifischer Hash-Anteil (z. B. für Gutschein-URLs o. ä.)
  "birthday": 976116400000 // Geburtstag als Unix-Zeitstempel in Millisekunden → entspricht: 2000-12-07T00:00:00Z
}

Sicherheit: Die Bereitstellung des Benutzer-Hashs gilt als die sicherste Methode zur Identifizierung des Benutzers. Da der Benutzer-Hash nicht erraten werden kann, zeigt die Transaktion, dass der Benutzer anhand seines Barcodes identifiziert wurde.

Benutzersuche per Abfrage

Wenn du nach einem Nutzer suchen möchtest, kannst du den folgenden GET-Endpunkt verwenden:

https://[instance]/BonusPointManagement/UserData/?query=[searchQuery]

Du musst die searchQuery (url-codiert) angeben, damit das System mögliche UserData-Objekte vorschlagen kann (maximal 50 Vorschläge). Jedes Objekt enthält

• die 4 letzten Ziffern des eindeutigen Benutzer-Hashs, damit eine grundlegende Authentifizierung möglich ist.
• die Benutzerkennung
• den Vornamen
• den Nachnamen
• die E-Mail Adresse
• die Anzahl der aktuellen Punkte

Das Antwortformat der Anfrage ist:

{"Vorschläge": 
 [ { "id":241, "preName": "Max", "name": "Mustermann", "eMail":null, "currentBonusPoints":50, "uniqueUserHashPart": "S5FA", "birthday":0 }, ... ] }

Bitte beachte, dass du im Falle eines gesuchten Benutzers eine zusätzliche Benutzervalidierung durchführen solltest (z.B. den Benutzerpass überprüfen). Andernfalls könnte es sein, dass der Nutzer eine falsche Nutzung seines Kontos behauptet und du die korrekte Nutzung nicht nachweisen kannst.

Sicherheit: Die Bereitstellung des Nutzers als Suchobjekt ist weniger sicher als die Verwendung des Nutzer-Hashs. Da ein Nutzername erraten werden kann, sollte der Kassenassistent eine zusätzliche Verifizierung verlangen, z. B. einen Personalausweis.

Benutzererstellung

Wenn du die Benutzererstellung unterstützen möchtest, kannst du mit dem folgenden GET-Endpunkt überprüfen, ob die angegebene E-Mail-Adresse bereits verwendet wird:

https://[instance]/BonusPointManagement/UserData/eMail?email=[email]

Du musst eine gültige E-Mail-Adresse angeben (url-codiert). Das System gibt dir die Information, ob die E-Mail-Adresse bereits verwendet wird (in diesem Fall empfiehlt sich die Suche nach dem richtigen Benutzer).

{"emailInUse":true}

Um einen neuen Benutzer anzulegen, kannst du eine POST-Anfrage an den Endpunkt senden:

https://[instance]/BonusPointManagement/UserData/

Du musst das folgende JSON-Objekt als POST-Body bereitstellen:

{ "preName": "Maria", "name": "Musterfrau", "eMail": "maria@repalogic.com", "uniqueUserHash": "4MDQAP8ZK2M4GT6" }

Im Beitragstext muss die eMail oder der uniqueUserHash angegeben werden. Wenn die eMail-Adresse nicht leer ist, erhält der Nutzer eine Registrierungs-eMail-Benachrichtigung, mit der er einen individuellen Login für das Webportal erstellen kann. Wenn der uniqueUserHash leer ist, wird er automatisch generiert. Mit diesem Ansatz kannst du dem Nutzer explizit einen eindeutigen Nutzer-Hash zuweisen (z.B. durch Einscannen einer bereits gedruckten Kundenkarte mit vorgegebenem Hash-Wert).

Die Antwort liefert die gespeicherten Daten:

{"id":255, "preName": "Maria", "name": "Musterfrau", "eMail": "maria@repalogic.com", "currentBonusPoints":0, "uniqueUserHashPart": "4MDQ", "birthday":0}

Coupon-Verwaltung

TYRIOS Coupons unterstützt digitale und analoge Coupons. Beide sind in der Regel als gedruckte Coupons verfügbar (sie werden also physisch bereitgestellt). Der Unterschied liegt in der Handhabung:

• Digitale Coupons müssen im Kassenprozess geprüft werden, um zu wissen, wie viel Geld für den Coupon zur Verfügung steht. Digitale Coupons können teilweise eingelöst werden und es ist möglich, dass der Kunde das Geld vom Coupon auf sein Benutzerkonto lädt.
• Analoge Coupons können nicht teilweise eingelöst werden. Es kann nur der gesamte Gutscheinwert verwendet werden. Analoge Gutscheine müssen also vom Unternehmen entgegengenommen und zentral eingelöst werden. Nach diesem Vorgang muss der Coupon gelöscht werden.

TYRIOS eCash unterstützt beide Arten parallel, indem es separate Coupon-Code-Muster verwendet. Mit dem Coupon-Code wird ein Coupon identifiziert.

Ein Coupon hat typischerweise folgende Datenstruktur:

{
  "id": 123, // automatisch vergebene ID des Coupons
  "couponCode": "ABCDEFGU", // eindeutiger, einmaliger Gutscheincode
  "couponValue": 12, // aktueller Wert des Coupons (z. B. in Euro)
  "originalValue": null, // ursprünglicher Wert des Coupons, falls abweichend (z. B. bei Teil-Einlösung)
  "validUntil": 1735686000000 // Gültigkeitsende als Unix-Timestamp in Millisekunden → entspricht: 2025-12-31T23:00:00Z
}

Je nach Transaktionsmodus reicht es aber auch aus, einfach den couponCode anzugeben. Darauf wird im Folgenden noch näher eingegangen.

Definition des Couponwerts

In den meisten Fällen ist ein Couponwert vordefiniert. Wenn du also einen CouponCode verwendest, erhältst du auch den entsprechenden Couponwert vom System. Es ist jedoch möglich, dass du mit Hilfe der API eigene Coupons erstellst. Wenn du einen Couponcode verwendest, der bisher noch nicht benutzt wurde, steht es dir frei, einen individuellen Couponcode anzugeben. Dies ist in allen drei Modi möglich.

TYRIOS eCash prüft den Coupon automatisch. Wenn dein verwendeter Gutscheincode also bereits einen Wert hat, ist es nicht möglich, ihn zu überschreiben.

Transaktionserstellung

Der Transaktionsdienst bietet eine Schnittstelle, um Transaktionen direkt zu erstellen. Standardmäßig wird die Transaktion sofort validiert und gespeichert. Es ist jedoch möglich, eine Transaktion im Entwurfsmodus zu erstellen, so dass sie zuerst ausgewertet wird. In diesem Fall prüft das eCash-System, ob der Benutzer korrekt ist (falls angegeben), ob die Gutscheincodes korrekt sind (falls angegeben) und was passieren würde, wenn die Transaktion gespeichert wird.

Dieser Ansatz ist sehr hilfreich, wenn du das eCash-System in dein Kassensystem integrieren willst. Du kannst jederzeit zum eCash-Terminal gehen und die Transaktion im Browser simulieren. So siehst du, was das Terminal sendet und was das System als Ergebnis liefert. Die Webdeveloper-Symbolleiste in Chrome und Firefox gibt dir alle nötigen Informationen, um eine Transaktion zu debuggen.

Das eCash-System unterstützt 5 verschiedene Transaktionsarten

1. pos-Modus: Dies ist der am häufigsten verwendete Modus, bei dem der Kunde einen Artikel kauft und sein Bonuspunktekonto zur Reduzierung des Zahlungsbetrags nutzen möchte. Darüber hinaus unterstützt diese Methode den Kauf mit einem Gutscheincode
   1. Wenn dieser nicht angegeben wird, wird der Gutschein direkt für die Zahlung verwendet. Wenn der Zahlungsbetrag geringer ist als der Gutscheinwert, ist der verbleibende Gutscheinwert noch auf dem Gutscheincode verfügbar.
   2. Wird der Nutzer angegeben, aber kein Gutscheincode, wird die Anzahl der Bonuspunkte des Nutzers für die Zahlung berücksichtigt (es ist nicht möglich, die verfügbaren Bonuspunkte NICHT zu berücksichtigen).
   3. Wenn der Nutzer und ein Gutscheincode angegeben werden, wird der Gutscheinwert in Bonuspunkte umgewandelt und die insgesamt verfügbaren Punkte (Konto + Gutscheinwert) werden verwendet. Der Coupon wird vollständig auf das Benutzerkonto übertragen, der Coupon wird also deaktiviert.
   4. Wenn der Benutzer und der Coupon angegeben werden, aber kein totalValue angegeben wird, wird der Couponwert dem Benutzerkonto zugewiesen und der Couponcode wird ungültig (dies ist ein Sonderfall von c).
2. coupon-Modus: In diesem Fall möchte der Kunde einen Coupon auf sein Benutzerkonto buchen. Dies ist das Gleiche wie 1.4, allerdings ohne Angabe eines Gesamtwerts. Die Implementierung ist optional.
3. coupon-Aktivierung: Ein frei zur Verfügung gestellter, aber eindeutiger Coupon-Code (8 Zeichen) wird aktiviert. Wenn die UserData bereitgestellt werden, kann die verfügbare Menge an Bonuspunkten des Nutzers als Bezahlung für den neuen Coupon verwendet werden.
4. bargeldmodus: In diesem Modus kann der Nutzer die verfügbaren Punkte auf seinem Konto erhöhen, indem er die Punkte kauft. Dieser Antrag kann auch verwendet werden Integration ist optional
5. sonderpunkte-Modus: In diesem Modus ist es möglich, die Punkte direkt dem eCash-Konto des Nutzers zuzuweisen. Die Integration ist optional

Allgemeiner Workflow

Grundsätzlich ist es möglich, eine Transaktion direkt zu erstellen, ohne vorher nach einem Nutzer zu suchen oder Daten zu validieren. In diesem Fall kann jedoch davon ausgegangen werden, dass bei der Erstellung der Transaktion ein Fehler auftreten kann. Das kann je nach Integration in Ordnung sein.

Im Allgemeinen empfehlen wir eine Integration mit drei Schritten:

1. kundenauswahl / Validierung
2. transaktionssimulation
3. transaktionsausführung

Dieser Arbeitsablauf ist im folgenden Diagramm zu sehen:

Die erforderlichen Daten für die Transaktionsbereitstellung / Transaktionsbestätigung hängen von der Transaktionsart ab und werden im Folgenden beschrieben. Es empfiehlt sich, einen Blick auf das Bonuspunkt-Terminal zu werfen, um einen Eindruck von der Funktionsweise des Systems zu bekommen.

Endpunkt

Es werden 4 verschiedene Transaktionsarten unterstützt, für die es jeweils einen eigenen Endpunkt gibt

https://[instance]/BonusPointManagement/BonusPointTransaction/(cash|specialPoints|pos|coupon|couponActication)

Alle Endpunkte haben gemeinsam, dass sie einen Entwurfsmodus unterstützen, indem sie den Endpunkt mit dem GET-Parameter "draft=true" erweitern. Der Entwurfsmodus legt fest, dass die Daten validiert werden sollen und die Transaktion simuliert, aber nicht ausgeführt wird. Dadurch ist es möglich, dieselbe Logik für die Simulation und die Ausführung zu verwenden.

Benutzerzuordnung

In den meisten Fällen wird die Transaktion zwischen einem Endbenutzer (dem Kunden) und einem Unternehmen (BonusPointSharingCompany) erstellt. Die Benutzerinformationen werden im Feld "UserData" gespeichert. Es gibt drei verschiedene Methoden, um die UserData zuzuweisen:

1. Im einfachsten Fall gibst du einfach einen eindeutigen Benutzer-Hash an. Dieser Benutzer-Hash wird in der Regel durch Kundenkarten, die Bonuspunkte-App oder ähnliche Techniken bereitgestellt. Er kann mit einem Barcode (Code128 kodiert) gescannt werden. Der userMode ist "HASH".
2. Wenn du den Benutzer-Hash nicht kennst, kannst du anhand des Vor- und Nachnamens nach einem Benutzer suchen (für die Suche gibt es einen eigenen Endpunkt). In diesem Fall musst du ein Benutzerobjekt in Kombination mit userMode="SEARCH" angeben.
3. Es ist auch möglich, über den Transaktionsdienst direkt einen neuen Endnutzer anzulegen. So kann ein Kunde direkt am Bonuspunktesystem teilnehmen, ohne dass er separate Dokumente unterschreiben muss. In diesem Fall erhält der Nutzer eine Einladungsmail. Ähnlich wie bei der Suche stellst du ein vollständiges Benutzerobjekt als UserData in Kombination mit userMode="CREATE" bereit

Transaktionsdaten

Transaktionen werden über Transaktionsobjekte abgewickelt. Aus Sicht der Implementierung erstellst du ein Transaktionsobjekt, sendest dieses Objekt an den Server und erhältst im Gegenzug ein geprüftes und abgeschlossenes Transaktionsobjekt.

Ein Transaktionsobjekt kann die folgenden Daten enthalten

Transaktionsbeispiele

Wir werden jetzt ins Detail gehen, um verschiedene Transaktionstypen für die wichtigsten Anwendungsfälle zu erstellen. Alle Anfragen werden mit draft=true erstellt (und somit wird die Transaktion nicht persistiert).

Die BonusPointSharingCompany wird automatisch vom System anhand der Anmeldedaten zugewiesen. Jede Transaktion hat also einen Benutzer (optional) und eine BonusPointSharingCompany als Transaktionspartner

Standardtransaktion mit Benutzer-Hash

https://[instance]/service/BonusPointManagement/BonusPointTransaction/pos?draft=true

{ UserData: "UQBUFDJALK4WXYC", enablePointRedemption: true, productGroup: "Hose", totalAmount: 33, userMode: "HASH", }

{
  "BonusPointCouponData": null, // Daten zu einem Coupon, falls vorhanden
  "BonusPointSharingCompany": {
    "id": 6,
    "companyName": "...",
    "street": "...",
    "streetNo": "...",
    "postCode": "...",
    "city": "..."
    // weitere optionale Adress-/Firmendetails
  },
  "BonusPointTransactionDataDetail": null, // Detaildaten zur Transaktion, optional
  "ClearingBillData": null, // Referenz auf Clearing-Rechnung, falls vorhanden
  "FeeBillData": null, // Referenz auf Gebührenrechnung, falls vorhanden
  "UserData": {
    "id": 1,
    "preName": "Max",
    "name": "Mustermann",
    "eMail": "max.mustermann@repalogic.com"
    // weitere Felder wie Geburtsdatum, etc. möglich
  },
  "availableObtainedPoints": 62, // aktuell verfügbare (nicht eingelöste) Punkte
  "bonusPointMode": "percentage", // Berechnungsmodus: z. B. "percentage", "fixed"
  "bonusPointPercentage": 0.02, // 2% Bonuspunkte auf Umsatz
  "clearingCreated": null, // ob ein Clearing erzeugt wurde
  "couponPoints": null, // durch Coupon generierte Punkte, falls vorhanden
  "employeeNumber": null, // Mitarbeiterkennung, falls benötigt
  "enablePointRedemption": true, // ob Punkte eingelöst werden dürfen
  "id": null, // ID der Transaktion, wird meist automatisch gesetzt
  "obtainedPoints": 62, // in dieser Transaktion verdiente Punkte
  "obtainedPointsVali

Standardtransaktion mit Benutzerobjekt (von der Benutzersuche bereitgestellt)

https://[instance]/service/BonusPointManagement/BonusPointTransaction/pos?draft=true

{
  "UserData": {
    "id": 1,
    "preName": "Max",
    "name": "Mustermann",
    "eMail": "max.mustermann@repalogic.com"
    // weitere Felder wie Geburtstag, Bonuspunkte etc. möglich
  },
  "enablePointRedemption": true, // Punkte dürfen eingelöst werden
  "productGroup": "Hose",         // Produktgruppe des Kaufs
  "totalAmount": 33,             // Gesamtbetrag der Transaktion
  "userMode": "SEARCH"           // Benutzer wurde über Suche identifiziert (nicht z. B. per Hash)
}

{
  "BonusPointCouponData": null,
  "BonusPointSharingCompany": {
    "id": 6,
    "companyName": "...",
    "street": "...",
    "streetNo": "...",
    "postCode": "...",
    "city": "..."
  },
  "BonusPointTransactionDataDetail": null,
  "ClearingBillData": null,
  "FeeBillData": null,
  "UserData": {
    "id": 1,
    "preName": "Max",
    "name": "Mustermann",
    "eMail": "max.mustermann@repalogic.com"
  },
  "availableObtainedPoints": 62,
  "bonusPointMode": "percentage",
  "bonusPointPercentage": 0.02,
  "clearingCreated": null,
  "couponPoints": null,
  "employeeNumber": null,
  "enablePointRedemption": true,
  "id": null,
  "obtainedPoints": 62,
  "obtainedPointsValidUntil": 1672527600000,
  "productGroup": "Hose",
  "redeemedPoints": 213,
  "remainingAmount": 30.87,
  "resultingPoints": 62,
  "startPoints": 213,
  "totalAmount": 33,
  "transactionFee": 0,
  "transactionTime": 1572351844000,
  "transactionType": "bonuspoint",
  "use4Clearing": null,
  "use4Invoice": null,
  "userMode": "SEARCH"
}

Standardtransaktion mit Benutzererstellung

https://[instance]/service/BonusPointManagement/BonusPointTransaction/pos?draft=true

{
  "UserData": {
    "preName": "Maria",
    "name": "Mustermann",
    "eMail": "maria.mustermann@repalogic.com"
  },
  "enablePointRedemption": true,
  "productGroup": "Hose",
  "totalAmount": 33,
  "userMode": "CREATE"
}

{
  "UserData": {
    "id": null,
    "preName": "Maria",
    "name": "Mustermann",
    "eMail": "maria.mustermann@repalogic.com"
  },
  "totalAmount": 33,
  "productGroup": "Hose",
  "bonusPointMode": "percentage",
  "bonusPointPercentage": 0.02,
  "obtainedPoints": 66,
  "redeemedPoints": 0,
  "remainingAmount": 33,
  "resultingPoints": 66,
  "startPoints": 0,
  "availableObtainedPoints": 66,
  "enablePointRedemption": true,
  "transactionType": "bonuspoint",
  "userMode": "CREATE"
}

Standardtransaktion mit Coupon (ohne Benutzer)

Bitte beachte. Dieses Beispiel bezieht sich auf eine vollständig digitalisierte Umgebung, in der es möglich ist, Gutscheine mit einem höheren Wert als die gekauften Artikel zu verwenden. In einer teilweise digitalisierten Umgebung wird das System den Coupon nicht akzeptieren.

https://[instance]/service/BonusPointManagement/BonusPointTransaction/pos?draft=true

{
  "BonusPointCouponData": [
    { "couponCode": "AB4DEFGH" }
  ],
  "enablePointRedemption": true,
  "productGroup": "Hose",
  "totalAmount": 33,
  "useCouponData": true,
  "userMode": "HASH"
}

{
  "BonusPointCouponData": [
    {
      "couponCode": "AB4DEFGH",
      "couponValue": 17,
      "validUntil": 1672527600000
    }
  ],
  "startPoints": 5000,
  "redeemedPoints": 3300,
  "resultingPoints": 1700,
  "remainingAmount": 0,
  "totalAmount": 33,
  "transactionType": "bonuspoint",
  "userMode": "HASH"
}

Standardtransaktion mit Coupon und Benutzer

Bitte beachte. Da der Benutzer in der Anfrage genannt wird, wird der Restwert des Gutscheins direkt dem Benutzer zugeordnet, der Gutscheinwert auf 0 gesetzt und somit der Gutschein deaktiviert. Dieser Anwendungsfall ist also auch in teilweise digitalisierten Umgebungen möglich. Der Nutzer kann also mit Gutscheinen bezahlen, die größer als der Verkaufsbetrag sind. Mit diesem Ansatz ist es möglich, Kunden beim Bezahlen mit größeren Gutscheinwerten zu unterstützen.

https://[instance]/service/BonusPointManagement/BonusPointTransaction/pos?draft=true

{
  "BonusPointCouponData": [{ "couponCode": "AB4DEFGH" }],
  "enablePointRedemption": true,
  "productGroup": "Hose",
  "totalAmount": 33,
  "useCouponData": true,
  "UserData": "UQBUFDJALK4WXYC",
  "userMode": "HASH"
}

{
  "BonusPointCouponData": [
    {
      "couponCode": "AB4DEFGH",
      "couponValue": 0,
      "validUntil": 1672527600000
    }
  ],
  "couponPoints": 5000,
  "startPoints": 213,
  "redeemedPoints": 3300,
  "resultingPoints": 1913,
  "obtainedPoints": 0,
  "remainingAmount": 0,
  "totalAmount": 33,
  "UserData": {
    "preName": "Max",
    "name": "Mustermann",
    "eMail": "max.mustermann@repalogic.com"
  },
  "userMode": "HASH"
}

Coupon-Transaktion (Verkauf eines Coupons) ohne Benutzer und Coupon-Erstellung

https://[instance]/service/BonusPointManagement/BonusPointTransaction/couponActivation?draft=true

{ UserData: null BonusPointCouponData:[{couponCode: "AB4DEFGH", "couponValue": 50}], couponValue: 50, enablePointRedemption: true, userMode: "HASH" }

{
  "transactionType": "coupon-activation",
  "BonusPointCouponData": [
    {
      "couponCode": "AB4DEFGH",
      "couponValue": 50,
      "validUntil": 1672527600000,
      "mode": "creation"
    }
  ],
  "obtainedPoints": 5000,
  "totalAmount": 50,
  "remainingAmount": 50,
  "redeemedPoints": 0,
  "startPoints": 0,
  "resultingPoints": 0,
  "couponPoints": null
}

Coupon-Transaktion (Verkauf eines Coupons) ohne Benutzer und Coupon-Aktivierung (Coupon ist bereits mit einem Wert registriert)

https://[instance]/service/BonusPointManagement/BonusPointTransaction/couponActivation?draft=true

{ UserData: null BonusPointCouponData:[{couponCode: "AB4DEFGH", "couponValue":50}], enablePointRedemption: true, userMode: "HASH" }

{
  "transactionType": "coupon-activation",
  "BonusPointCouponData": [
    {
      "couponCode": "AB4DEFGH",
      "couponValue": 50,
      "validUntil": 1672527600000,
      "mode": "activation"
    }
  ],
  "obtainedPoints": 5000,
  "remainingAmount": 50,
  "redeemedPoints": 0,
  "UserData": null
}

Coupon-Transaktion (Verkauf eines Coupons) mit Benutzer

Der Unterschied zur obigen Anfrage besteht darin, dass der Nutzer seine verfügbaren Punkte nutzen kann, um einen Teil des Coupons zu bezahlen

https://[instance]/service/BonusPointManagement/BonusPointTransaction/couponActivation?draft=true

{
  "UserData": "UQBUFDJALK4WXYC",
  "bonusPointMode": "percentage",
  "bonusPointPercentage": 0.02,
  "BonusPointCouponData": [
    {
      "couponCode": "AB4DEFGH",
      "couponValue": 50
    }
  ],
  "enablePointRedemption": true,
  "obtainedPoints": 5000,
  "redeemedPoints": 0,
  "remainingAmount": 50,
  "resultingPoints": 0,
  "startPoints": 0,
  "totalAmount": 50,
  "userMode": "HASH"
}

{
  "transactionType": "coupon-activation",
  "couponCode": "AB4DEFGH",
  "couponValue": 50,
  "obtainedPoints": 5000,
  "redeemedPoints": 213,
  "remainingAmount": 47.87,
  "UserData": {
    "id": 1,
    "preName": "Max",
    "name": "Mustermann",
    ...
  },
  "startPoints": 213,
  "availableObtainedPoints": 0
}

Punkt-Transaktion mit Benutzer

https://[instance]/service/BonusPointManagement/BonusPointTransaction/specialPoints?draft=true

{ UserData: "UQBUFDJALK4WXYC" couponCode: null, enablePointRedemption: true, obtainedPoints: 50, productGroup: "Sonderaktion Wettbewerb", userMode: "HASH" }

{
  "transactionType": "specialPoints",
  "productGroup": "Sonderaktion Wettbewerb",
  "obtainedPoints": 50,
  "redeemedPoints": 0,
  "totalAmount": 0,
  "UserData": {
    "id": 1,
    "preName": "Max",
    "name": "Mustermann",
    ...
  },
  "startPoints": 213,
  "resultingPoints": 263
}

Fehlerbehandlung

Wenn das System die bereitgestellten Daten nicht verarbeiten kann, gibt es eine entsprechende Fehlermeldung und einen http-Statuscode 400 zurück.

Der Antwortkörper enthält einen Fehlertyp und eine Fehlermeldung. Die Meldung wird entsprechend den Spracheinstellungen des Benutzers (die in den Anmeldeinformationen angegeben sind) übersetzt.

{ error: "Exception", message: "Es existiert bereits ein identischer Eintrag." }