Web Vouchers Landing Page
You can retrieve information from the Hypersoft web vouchers and display it on your homepage, for example.
Note: Project work subject to planning
This is an area that requires detailed project planning.
The Hypersoft system is a flexible standard solution that can be used in a variety of configurations. The correct implementation of the functions described here requires specialist expertise and a clear comparison of your requirements and expectations.
Please note that not all Hypersoft employees or partners are trained to the same extent in each of these labelled subject areas.
For this reason, we characterise certain content as "project work requiring planning". We would like to ensure that you contact your Hypersoft sales partner or Hypersoft Support at an early stage in order to carry out the necessary planning and coordination.
This structured approach enables us to carefully analyse your requirements and implement them in a targeted manner.
Further topics: Vouchers, third-party vouchers - All
If you want to display the status of the current credit balance of web vouchers, we provide you with an interface for this. The sum can also only be displayed after entering a pin, the default is without PIN.
To read the voucher data from the Hypersoft portal and display it on a landing page, the interface is called up with the following URL:
https://myhypersoft.de/mobile-people.aspx?KN=<Customer number>&P=<Password>&GN=<Voucher number>&PIN=<Pin
(But see also: Web voucher URL for status request)
| <Customer number> | The customer number of the customer at Hypersoft. This parameter is fixed. |
| <Password> | The customer's stored interface password at Hypersoft. Can be created in the portal |
| <voucher number> | The 14-digit number of the voucher to be queried. This number is entered by the customer or passed as a parameter to your landing page. |
| <Pin> | The 4-digit PIN of the voucher to be queried. This number is entered by the customer or passed as a parameter to your landing page. The decision whether to use a PIN is a global system setting. |
| &B01 | This parameter can be used to retrieve the bonus scheme data. |
The interface returns a JSON object with all relevant data for the voucher. A valid URL with your data would be for example:
https://myhypersoft.de/mobile-people.aspx?KN=xxxxxxxxxxx&P=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&GN=49012072574964&PIN=7906
Examples of the landing pages...
https://landingpage-hypersoft.de/
Example with invitation amount:
https://landingpage-hypersoft.de/?HYGS=490100115203445625
Example code...
<?php
echo '<br />';
// Read out transferred voucher number with attached PIN
// either via query or via form
$GNPIN = $_GET['HYGS'];
if ($GNPIN == '') {$GNPIN = $_POST['HYGS'];
}
// no voucher number handed over?
if ($GNPIN == '') {
// then ask for voucher number
echo '<form method="get">';
echo 'Enter coupon number: <input type="text" name="HYGS"><br>'; echo '<inputtype="submit" value="Query coupon number">'; echo '</form>';
} else {
// Kontostand des gutscheins ausgebenecho 'Gutschein-Nr.: '.$GNPIN.'<br />';// PIN und Gutscheinnummer splitten$PIN = substr($GNPIN, -4);$GN = substr($GNPIN, 0, 14);// feste Daten des Kunden$KN = 'xxkdnrxx';$P = 'xxxxpwxxxxxx';// URL für die Abfrage mit SSL$URL = 'https://myhypersoft.de/mobile-people.aspx?KN='.$KN.'&P='.$P.'&PIN='.$PIN.'&GN='.$GN;//echo '$URL: '.$URL.'<br />';// Daten als JSON abfragen und in ein assoziatives Array dekodieren$seite = file_get_contents($URL);$array = json_decode($seite, true);//var_dump($array);echo '<br />';// nur wenn der Status = OK, dann ist die Abfrage in Ordnung// ansonsten Fehler ausgebenif ($array['Status'] != 'OK') {echo 'Fehler: '.$array['Status'];} else {$Kontostand = number_format($array['Kontostand'], 2);echo 'Kontostand: '.$Kontostand.' EUR';}
}
?>
Further topics: Web-Vouchers
Retrieving the bonus scheme details for a web voucher
The parameter &B=1 can be used optionally to retrieve web vouchers.
If this parameter is set, the response will also contain a 'Bonus' field in the JSON object. Without this parameter, the response is limited to the default voucher data.
The bonus object contains the bonus definitions stored in the portal that are relevant to the combination of customer number and web voucher number provided. The data returned therefore always relates specifically to the customer in question and the relevant voucher.
Example with bonus data:
https://myhypersoft.de/mobile-people.aspx?KN=<customer number>&P=<password>&GN=<voucher number>&PIN=<PIN>&B=1
Structure of the JSON provided:
Copy
JSON definition
{
"Ablaufdatum": JSON-Datumszeichenkette - immer mit dem Datum 31.12.2099 23:59:59 gefüllt, für zukünftige Erweiterungen,
"AktivierungFuerEinladungsgutscheinPerMail": Zeichenkette - wird nicht mehr benötigt, nur aus historischen Gründen noch enthalten,
"AktivierungFuerRabattgutscheinPerMail": Zeichenkette - wird nicht mehr benötigt, nur aus historischen Gründen noch enthalten,
"Einladungsbetrag": Numerischer Wert - noch vorhandener Einladungsbetrag,
"Einladungsbetragfilialen": Zeichenkette - Namen der teilnehmenden Filialen, bei denen der Einladungsbetrag eingelöst werden kann, mit ; getrennt,
"Einladungsbetragfilialenkundennummern": Zeichenkette - Hypersoft-Kundennummern der teilnehmenden Filialen, bei denen der Einladungsbetrag eingelöst werden kann, mit ; getrennt,
"Gesperrt": Boolean - true = gesperrter Gutschein, false = Gutschein kann verwendet werden,
"Gutscheinlimit": Integer - immer mit 0 gefüllt, für zukünftige Erweiterungen,
"Gutscheinnummer": Zeichenkette - Gutscheinnummer,
"GutscheinnummerExistiertUndPinOK": Boolean - true = Gutschein wurde gefunden, false = Gutschein wurde nicht gefunden,
"Kontostand": Numerischer Wert - aufgeladener Betrag,
"Protokoll": Liste von Aktionen die auf dem Gutschein stattgefundenen haben oder null, wenn keine Aktionen vorhanden
Es werden nur die Aktionen Gutscheinbuchung, Gutscheinaktivierung, Gutscheinaufladung oder Gutscheinsperrung ausgegeben.
Liste besteht aus einzelnen JSON-Objekten:
[
{
"Aktion": Zeichenkette - Bezeichnung der Aktion, kann Gutscheinbuchung, Gutscheinaktivierung, Gutscheinaufladung oder Gutscheinsperrung sein,
"Ausgangsbetrag": Numerischer Wert - Betrag auf dem Gutschein vor der Aktion,
"Betrag": Numerischer Wert - Betrag, die auf dem Gutschein angewendet wird,
"Details": Zeichenkette - Detailangaben zu dieser Aktion,
"Endbetrag": Numerischer Wert - Betrag auf dem Gutschein nach der Aktion,
"IP": Zeichenkette - IP-Adresse von der die Aktion ausgelöst wurde,
"Info": Zeichenkette - Infoangaben zu dieser Aktion,
"Kundennummer": Zeichenkette - Hypersoft-Kundennummer von der die Aktion ausgelöst wurde,
"Status": Zeichenkette - für zukünftige Erweiterungen,
"Zeitpunkt": JSON-Datumszeichenkette - Zeitpunkt an dem die Aktion durchgeführt wurde
}
],
"Rabattfilialen": Zeichenkette - Namen der teilnehmenden Filialen, bei denen der Rabatt eingelöst werden kann, mit ; getrennt,
"Rabattfilialenkundennummern": Zeichenkette - Hypersoft-Kundennummern der teilnehmenden Filialen, bei denen der Rabatt eingelöst werden kann, mit ; getrennt,
"Rabattprozent": Numerischer Wert - Rabatt in Prozent,
"RegistrierungFuerEinladungsgutscheinNotwendig": Zeichenkette - wird nicht mehr benötigt, nur aus historischen Gründen noch enthalten,
"RegistrierungFuerRabattgutscheinNotwendig": Zeichenkette - wird nicht mehr benötigt, nur aus historischen Gründen noch enthalten,
"Status": Zeichenkette - "OK", wenn alles in Ordnung, ansonsten enthält die Zeichenkette die Fehlermeldung,
"letzter_Zugriff": JSON-Datumszeichenkette - letzter Zugriff aus den im Protokoll zurückgegebenen Aktionen, wenn nicht vorhanden dann mit dem Datum 01.01.2014 00:00:00 gefüllt,
"Bonus": JSON-Objekt mit den Angaben für das Bonussystem, nur vorhanden bei Übergabe des Parameters B=1; ist null, wenn kein Bonussystem vorhanden
{
"Bonusaktionen": Liste von Bonusaktionen die definiert sind oder null, wenn keine Bonusaktionen vorhanden
Liste besteht aus einzelnen JSON-Objekten:
[
{
"BenefitArtikelAufBelegAusblenden": Boolean - true = Text aus OptionalerTextAufBeleg statt Artikelnamen ausgeben, false - Artikelnamen ausgeben,
"Benefits": Liste von Benefits die definiert sind oder null, wenn keine Benefits vorhanden
Liste besteht aus einzelnen JSON-Objekten:
[
{
"ArtikelProductID": Integer - ProductID aus dem Kassensystem,
"Artikelbezeichnung": Zeichenkette - Bezeichnung des Artikels,
"Bezeichnung": Zeichenkette - Bezeichnung des Benefits,
"Value": Integer - notwendige Punkte zur Einlösung,
"Verlustgrundbezeichnung": Zeichenkette - Bezeichnung des Verlustgrundes,
}
],
"Benefittyp": Integer - 0 oder 1; siehe Benefittypbezeichnung,
"Benefittypbezeichnung": Zeichenkette - bei Benefittyp = 0 - "---", 1 - "Artikel für Punkte",
"Bezeichnung": Zeichenkette - Bezeichnung der Bonusaktion,
"Bonusse": Liste von Bonusse die definiert sind oder null, wenn keine Bonusse vorhanden
Liste besteht aus einzelnen JSON-Objekten:
[
{
"ArtikelProductID": Integer - ProductID aus dem Kassensystem,
"Artikelbezeichnung": Zeichenkette - Bezeichnung des Artikels,
"Limit": Integer - wenn = 0, dann kein Limit, sonst bei Bonustyp = 0 - immer 0, 1 - immer 0, 2 - max. Umsatz pro Besuch (Vorgang), 3 - max. Vorgänge pro Tag,
"Value": Integer - bei Bonustyp = 0 - immer 0, 1 - Punkte pro Artikel, 2 - Punkte pro Besuch (Vorgang), 3 - Punkte auf Umsatz,
}
],
"Bonustyp": Integer - 0, 1, 2, oder 3; siehe Bonustypbezeichnung,
"Bonustypbezeichnung": Zeichenkette - bei Bonustyp = 0 - "---", 1 - "Punkte pro Artikel", 2 - "Punkte pro Besuch (Vorgang)", 3 - "Punkte auf Umsatz",
"Ende": JSON-Datumszeichenkette - bis wann die Bonusaktion läuft, wenn nicht vorhanden dann mit dem Datum 01.01.0001 00:00:00 oder null gefüllt,
"EndeDesBenefits": JSON-Datumszeichenkette - bis wann die Benefits eingelöst werden können, wenn nicht vorhanden dann mit dem Datum 01.01.0001 00:00:00 oder null gefüllt,
"OptionalerTextAufBeleg": Zeichenkette - Text der auszugeben ist, wenn BenefitArtikelAufBelegAusblenden = true,
"Punkte": Integer - gesammelte Punkte des Gutscheins in dieser Bonusaktion,
"Standorte": Liste von Standorten die an der Bonusaktion teilnehmen oder null, wenn keine Standorte vorhanden
Liste besteht aus einzelnen JSON-Objekten:
[
{
"Kundennummer": Integer - Hypersoft-Kundennummer,
}
],
"Start": JSON-Datumszeichenkette - ab wann die Bonusaktion läuft, wenn nicht vorhanden dann mit dem Datum 01.01.0001 00:00:00 oder null gefüllt,
}
],
"Error": Integer - 0, wenn alles in Ordnung bei der Bonusabfrage, ansonsten eine Fehlernummer,
"ErrorMessage": Zeichenkette - "", wenn alles in Ordnung bei der Bonusabfrage, ansonsten enthält die Zeichenkette die Fehlermeldung,
"LetzteAktivitaet": JSON-Datumszeichenkette - letzte Bonusaktivität des Gutscheins, wenn nicht vorhanden dann mit dem Datum 01.01.0001 00:00:00 oder null gefüllt,
}
}
Example in PHP:
Copy
<?php
// Damit file_get_contents erlaubt ist, muss allow_url_fopen und allow_url_include angeschaltet sein.
// phpinfo();
date_default_timezone_set('Europe/Berlin');
enum MyDateFormatCase {
case WithTime;
case WithoutTime;
}
function ConvertJsonDateToString($DateString, MyDateFormatCase $MyDateFormat = MyDateFormatCase::WithTime)
{
if (is_null($DateString)) {
return "---";
}
else {
$ConvertedDate = explode('(', $DateString);
$ConvertedDate = explode(')', end($ConvertedDate));
$ConvertedDate = reset($ConvertedDate);
switch ($MyDateFormat) {
case MyDateFormatCase::WithoutTime:
return date("d.m.Y", ((int)$ConvertedDate)/1000);
break;
default:
return date("d.m.Y H:i:s", ((int)$ConvertedDate)/1000);
break;
}
}
}
// Übergebene Gutscheinnummer mit angehängter PIN auslesen
// entweder über Query oder über Form
$GNPIN = $_GET['HYGS'];
if ($GNPIN == '') {
$GNPIN = $_POST['HYGS'];
}
// keine Gutscheinnummer übergeben?
if ($GNPIN == '') {
// dann Gutscheinnummer und PIN abfragen
echo '<form method="get">';
echo '<table>';
echo '<tr class="flex-cell"><td>Gutscheinnummer eingeben:</td><td><input type="text" name="HYGS"></td><tr>';
echo '</table>';
echo '<input type="submit" value="Gutschein abfragen.">';
echo '</form>';
}
else {
echo '<table><tr><td>';
// PIN und Gutscheinnummer splitten
$PIN = substr($GNPIN, -4);
$GN = substr($GNPIN, 0, 14);
// feste Daten des Kunden
// Kundennummer
$KN = <Kundennummer>;
// Passwort
$P = <Passwort>;
// URL für die Abfrage mit SSL
$URL = 'https://myhypersoft.de/mobile-people.aspx?KN='.$KN.'&P='.$P.'&PIN='.$PIN.'&GN='.$GN.'&B=1';
// Daten als JSON abfragen und in ein assoziatives Array dekodieren
$seite = file_get_contents($URL);
$array = json_decode($seite, true);
echo '<br />';
//var_dump($array);
echo '<br />';
// nur wenn der Status = OK, dann ist die Abfrage in Ordnung
// ansonsten Fehler ausgeben
if ($array['Status'] != 'OK') {
echo '<br>Fehler: '.$array['Status'];
}
else {
// Gutscheindaten ausgeben
if ($array['Gesperrt']) {
echo '<br />Dieser Gutschein ist GESPERRT.<br />';
}
echo '<br />Gutschein-Nr.: '.$GNPIN;
$Kontostand = number_format($array['Kontostand'], 2);
echo '<br />Kontostand: '.$Kontostand.' EUR';
$Rabattprozent = number_format($array['Rabattprozent'], 2);
// Gibt es Rabatt auf der Karte?
if ($Rabattprozent > 0) {
echo '<br />Rabattprozent: '.$Rabattprozent.' Prozent';
}
$Einladungsbetrag = number_format($array['Einladungsbetrag'], 2);
// Gibt es Einladungsbetrag auf der Karte?
if ($Einladungsbetrag > 0) {
echo '<br />Einladungsbetrag: '.$Einladungsbetrag.' EUR';
}
$letzter_Zugriff = ConvertJsonDateToString($array['letzter_Zugriff']);
if (is_null($letzter_Zugriff)) {
echo '<br />letzter Zugriff: ---';
}
else {
if ($letzter_Zugriff == '01.01.2014 00:00:00') {
echo '<br />letzter Zugriff: ---';
}
else {
echo '<br />letzter Zugriff: '.$letzter_Zugriff;
}
}
// Protokolleinträge ausgeben
if (!is_null($array['Protokoll'])) {
if (count($array['Protokoll']) > 0) {
echo '<br />';
echo '<table border="1" width="100%">';
echo '<tr><td colspan="8"><b>Protokoll</b></td></tr>';
echo '<tr>';
echo '<td>Zeitpunkt</td>';
echo '<td>Kundennummer</td>';
echo '<td>Aktion</td>';
echo '<td>Ausgangsbetrag</td>';
echo '<td>Betrag</td>';
echo '<td>Endbetrag</td>';
echo '<td>Info</td>';
echo '<td>Details</td>';
echo '</tr>';
foreach ($array['Protokoll'] as $ProtokollValue) {
echo '<tr>';
echo '<td>'.ConvertJsonDateToString($ProtokollValue["Zeitpunkt"]).'</td>';
echo '<td>'.$ProtokollValue["Kundennummer"].'</td>';
echo '<td>'.$ProtokollValue["Aktion"].'</td>';
echo '<td>'.number_format($ProtokollValue["Ausgangsbetrag"], 2).'</td>';
echo '<td>'.number_format($ProtokollValue["Betrag"], 2).'</td>';
echo '<td>'.number_format($ProtokollValue["Endbetrag"], 2).'</td>';
echo '<td>'.$ProtokollValue["Info"].'</td>';
echo '<td>'.$ProtokollValue["Details"].'</td>';
echo '</tr>';
}
echo '</table>';
}
}
if (!is_null($array['Bonus'])) {
$array = $array['Bonus'];
// Bonussystem
echo '<br /><br /><b>Bonus</b><br />';
// Fehler im Bonussystem?
$Error = number_format($array['Error'], 2);
if ($Error > 0) {
echo '<br />Fehler: '.$array['ErrorMessage'];
}
else {
$letzter_Zugriff = ConvertJsonDateToString($array['LetzteAktivitaet']);
if (is_null($letzter_Zugriff)) {
echo '<br />letzter Zugriff: ---';
}
else {
if ($letzter_Zugriff == '01.01.0001 00:00:00') {
echo '<br />letzter Zugriff: ---';
}
else {
echo '<br />letzter Zugriff: '.$letzter_Zugriff;
}
}
// Bonusaktionen ausgeben
if (!is_null($array['Bonusaktionen'])) {
if (count($array['Bonusaktionen']) > 0) {
echo '<br />';
echo '<table border="1" width="100%">';
echo '<tr><td colspan="5"><b>Bonusaktionen</b></td></tr>';
echo '<tr>';
echo '<td>Bezeichnung</td>';
echo '<td>Start</td>';
echo '<td>Ende</td>';
echo '<td>Punkte</td>';
echo '<td>Ende des Benefits</td>';
echo '</tr>';
foreach ($array['Bonusaktionen'] as $BonusaktionValue) {
echo '<tr>';
echo '<tr><td colspan="5"> </td></tr>';
echo '<td><b>'.$BonusaktionValue["Bezeichnung"].'</b></td>';
echo '<td>'.ConvertJsonDateToString($BonusaktionValue["Start"], MyDateFormatCase::WithoutTime).'</td>';
echo '<td>'.ConvertJsonDateToString($BonusaktionValue["Ende"], MyDateFormatCase::WithoutTime).'</td>';
echo '<td>'.(int)$BonusaktionValue["Punkte"].'</td>';
echo '<td>'.ConvertJsonDateToString($BonusaktionValue["EndeDesBenefits"], MyDateFormatCase::WithoutTime).'</td>';
echo '</tr>';
// teilnehmende Standorte ausgeben
if (!is_null($BonusaktionValue['Standorte'])) {
if (count($BonusaktionValue['Standorte']) > 0) {
echo '<tr><td colspan="5">';
echo '<table border="1" width="100%">';
echo '<tr><td colspan="1"><b>teilnehmende Standorte</b></td></tr>';
echo '<tr>';
echo '<td>Kundennummer</td>';
echo '</tr>';
foreach ($BonusaktionValue['Standorte'] as $StandortValue) {
echo '<tr>';
echo '<td>'.(int)$StandortValue["Kundennummer"].'</td>';
echo '</tr>';
}
echo '</table>';
echo '</td></tr>';
}
}
// Bonusse ausgeben
if ((int)$BonusaktionValue['Bonustyp'] > 0) {
if (count($BonusaktionValue['Bonusse']) > 0) {
echo '<tr><td colspan="5">';
echo '<table border="1" width="100%">';
switch ((int)$BonusaktionValue['Bonustyp']) {
case 2:
echo '<tr><td colspan="3"><b>Bonustyp: '.$BonusaktionValue["Bonustypbezeichnung"].'</b></td></tr>';
echo '<tr>';
echo '<td>Punkte</td>';
echo '<td>max. Umsatz pro Besuch (Vorgang)</td>';
echo '<td>Artikel</td>';
break;
case 3:
echo '<tr><td colspan="3"><b>Bonustyp: '.$BonusaktionValue["Bonustypbezeichnung"].'</b></td></tr>';
echo '<tr>';
echo '<td>Punkte</td>';
echo '<td>max. Vorgänge pro Tag</td>';
echo '<td>Artikel</td>';
break;
default:
echo '<tr><td colspan="2"><b>Bonustyp: '.$BonusaktionValue["Bonustypbezeichnung"].'</b></td></tr>';
echo '<tr>';
echo '<td>Punkte</td>';
echo '<td>Artikel</td>';
break;
}
echo '</tr>';
foreach ($BonusaktionValue['Bonusse'] as $BonusValue) {
echo '<tr>';
echo '<td>'.(int)$BonusValue["Value"].'</td>';
switch ((int)$BonusaktionValue['Bonustyp']) {
case 2:
case 3:
if ((int)$BonusValue["Limit"] == 0) {
echo '<td>---</td>';
}
else {
echo '<td>'.(int)$BonusValue["Limit"].'</td>';
}
break;
default:
break;
}
echo '<td>'.$BonusValue["Artikelbezeichnung"].'</td>';
echo '</tr>';
}
echo '</table>';
echo '</td></tr>';
}
}
// Benefits ausgeben
if ((int)$BonusaktionValue['Benefittyp'] > 0) {
if (count($BonusaktionValue['Benefits']) > 0) {
echo '<tr><td colspan="5">';
echo '<table border="1" width="100%">';
echo '<tr><td colspan="2"><b>Benefittyp: '.$BonusaktionValue["Benefittypbezeichnung"].'</b></td></tr>';
echo '<tr>';
echo '<td>Benefit</td>';
echo '<td>Punkte</td>';
echo '</tr>';
foreach ($BonusaktionValue['Benefits'] as $BenefitValue) {
echo '<tr>';
echo '<td>'.$BenefitValue["Bezeichnung"].'</td>';
echo '<td>'.(int)$BenefitValue["Value"].'</td>';
echo '</tr>';
}
echo '</table>';
echo '</td></tr>';
}
}
}
echo '</table>';
}
}
}
}
}
echo '</td></tr></table>';
}
?>
In the portal, under Customer Loyalty > Web Vouchers > Settings, you can set your own password in the section labelled ‘Password for the landing page interface’. Please ensure that the password does not contain the characters ? and #. When saving, every '?' entered is therefore replaced by '!' and every '#' entered is replaced by '*'.
Further topics:
3rd party voucher integrations
Back to the overarching topic: MOBILE PEOPLE connections