NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Bedienerhandbuch NOVACOM Schnittstelle zu E-GUMA Gutscheinsystem
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Inhaltsverzeichnis
Inhalt Allgemein .................................................................................................................... 3
Funktionsumfang ......................................................................................................... 3
Voraussetzungen NT2.0 ........................................................................................ 3
Zugriff und Firewall - Einstellungen: ....................................................................... 3
Installation / Konfiguration ........................................................................................... 4
NovaTouch Control - BackOffice ............................................................................ 4
Interface-Partner einrichten ................................................................................... 4
Einrichtung Touch-Menüs für den Verkauf .............................................................. 8
FAQ ..................................................................................................................... 9
Verkauf und Einlösung von Gutscheinen an der NovaTouch-Kasse ................................ 10
Verkauf / Aktivierung von E-Guma - Gutscheinen .................................................. 10
Verkaufsstorno / Deaktivieren von E-Guma - Gutscheinen ..................................... 12
Einlösung von E-Guma - Gutscheinen ................................................................... 13
Einlösungsstorno von E-Guma - Gutscheinen ........................................................ 14
Gutscheininfo abfragen ....................................................................................... 15
Das E-Guma Portal .................................................................................................... 16
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Allgemein
Folgende Funktionen wurden implementiert:
Gutscheineinlösung über Gutscheinnummer Gutscheinverkauf von bereits vorgedruckten Gutscheinen Gutscheinverkauf von nicht vorgedruckten Gutscheinen (Depot-Gutscheinen)
Die Kommunikation erfolgt über HTTPS-Verschlüsselung.
Funktionsumfang
Gutscheine einlösen Ja
Gutscheine mit Positionslösung einlösen
Nein - nur Wertgutscheine können in NT eingelöst werden. Ein 'Leistungsgutschein' in E-Guma wird bei uns mit dem vorgegeben Wert aus E-Guma aktiviert oder eingelöst.
Einlösung stornieren Ja
Teileinlösung Ja
Gutschein-Guthaben abfragen Ja
Depot-Gutschein ausstellen (aktivieren)
Ja
Depot-Gutschein stornieren (deaktivieren)
Ja
Depot-Gutschein mit freiem Betrag ausstellen (aktivieren)
Ja
Mehrere API Keys Das Anbinden von mehreren API's pro Verkaufsort ist möglich.
Voraussetzungen NT2.0
NovaTouch ab Version 2017.1 Caché Datenbank ab Version 2008
Zugriff und Firewall - Einstellungen:
443/TCP
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Installation / Konfiguration
NovaTouch Control - BackOffice
Interface-Partner einrichten
Einstellungen
Parameter mögliche
Werte Beschreibung
Partnerkürzel EGUMA Frei verfügbares Partnerkürzel, es sollte lediglich auf Sonderzeichen verzichtet werden (/,|,-, etc.)
Bezeichnung "E-Guma Schnittstelle"
Frei verfügbare Bezeichnung für den Gutscheinpartner
Interfacegruppe E-GUMA VOUCHER
Interfacetypen-Auswahl für E-GUMA Gutscheinverwaltung (Anbindung über Webservice)
Übertragung ab Datum
Datum, ab welcher die Schnittstelle aktiviert ist - hat hier keine Relevanz, muss mit Startdatum ausgefüllt werden
Log-Level 1,2,3,9
Log Level für Ereignisjournal, je höher die Log-Level-Nummer eingestellt ist, um so detaillierter wird Journal geführt. - Achtung: Das Journal kann große Datenmengen bei Option '9' erzeugen und sollte daher nur zu Testzwecken kurzfristig aktiviert werden.
E-Guma Webservice Endpoint
https://api.e-guma.ch
URL des Interface-Partners E-GUMA
API Version 1.0 Derzeit wird die Version 1.0 der API von E-GUMA mit NovaTouch POS unterstützt (Stand 03.04.2017)
Artikelnummer für Gutscheinverkauf
Richten Sie einen neuen Artikel Gutschein ein, welcher keine MwSt. enthält und nicht umsatzrelevant ist.
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Import - Mappings
In der Sektion "Import Zuordnung API-Key je Outlet" kann entweder für alle Outlets ein API-Code hinterlegt werden, oder pro Outlet / Mandant ein eigener API-Code, der von E-GUMA zur Verfügung gestellt wird. Beim Verbindungsaufbau der Anfrage wird dann entweder der globale API-Code oder jener des Verkaufsortes (Outlet) der Kasse verwendet, wenn ein Code pro Verkaufsort hinterlegt wurde. Der API-Schlüssel fungiert häufig als eindeutiger Bezeichner und ein geheimes Token für die Authentifizierung beim Zugriff auf die Anwendungsprogrammierschnittstelle (API) .
Parameter mögliche
Werte Beschreibung
API Key
Der API-Key wird von E-GUMA zur Verfügung gestellt. Dieser Code ist für die Komunikation und Identifikation des Mandanten bei E-GUMA zwingend vorgesehen.
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Zahlungsarten
NovaTouch Control --> Verwaltung --> Parameter NovaTouch --> Betriebsorganisation - Zahlungsarten
Bei der Anlage der Zahlungsart muss das Inkassokennzeichen "13 - Gutscheineinlösung Partnersysteme" hinterlegt werden, damit an der Kasse die Kommunikation mit dem Interface-Partner zur Prüfung stattfinden kann.
Artikelstamm
Im Artikelstamm wird nun der in der Schnittstelle verwendete Artikel angelegt und der Gutschein-Artikelgruppe zugeordnet.
Der Artikel darf nicht mit Option 'Verkaufspreis änderbar' angelegt werden! Die Schnittstelle fragt bei Gutscheinen, die als 'Freibetrags-Gutscheine' im Depot angelegt wurden automatisch nach dem Preis des Gutscheines.
Wird der Artikel dennoch mit 'Verkaufspreis änderbar' angelegt, kommt es zu ungewollten
Differenzen zwischen Verkaufswerten und E-GUMA Werten!
Artikelstamm generell / Verkaufspreise / Artikelbehandlung
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Einrichtung Touch-Menüs für den Verkauf
Für den Verkauf in NovaTouch muß eine spezielle Artikeltaste im Touchmenü hinterlegt werden. Über den Eintrag im Feld Untermenü mit dem Format
'GUTSCHEIN:<PARTNERKÜRZEL>'
wird automatisch der Gutscheinartikel z.B. 10000001, der in der Schnittstelle definiert wurde, für den Verkauf der vorgedruckten Gutscheine über NovaTouch verwendet.
Mehrere Mandanten für E-Guma
Sind in NovaTouch Control mehrere Mandanten (Partner) für E-GUMA definiert worden, so ist pro Partner (Mandant) eine Artikeltaste zu definieren.
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
FAQ
Mögliche Fehler - Resultcodes von E-GUMA:
Code Beschreibung Lösung
400 Bad Request - Often missing a required parameter.
Ein für die Anfrage notwendiger Parameter wurde nicht angegeben - Programmierung NC verständigen.
401 Unauthorized - No valid API key provided.
Nicht autorisiert - Der API-Key fehlt oder ist ungültig. Einen gültigen API-Key bei E-GUMA anfordern
500 Server errors - something went wrong on E-GUMA's end.
Server Probleme auf Seiten E-GUMA's. Nach einiger Zeit nochmals versuchen bzw. E-GUMA Support informiere
Fragen & Lösungen
Frage / Problem Beschreibung / Lösung
Unter „Funktionen“ - „Informationen E-GUMA Schnittstelle“ kann man eine Gutscheinnummer auf Gültigkeit prüfen. Ist eine eingegebene Gutscheinnummer in E-GUMA nicht auffindbar, so erhält man die Informationsmeldung 'Der Gutschein ist nicht vorhanden'. Auch beim Einlösungsversuch oder Verkaufsversuch erhalten Sie eine entsprechende Hinweismeldung.
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Verkauf und Einlösung von Gutscheinen an der NovaTouch-Kasse Diese Anleitung erläutert lediglich die Verwendung von E-Guma-Gutscheinen über die Schnittstelle in NovaTouch POS. Das Handling über die E-Guma Platform ist nicht Bestandteil dieser Anleitung
Verkauf / Aktivierung von E-Guma - Gutscheinen
Über die NovaTouch Kasse können nur sogenannte Depot-Gutscheine verkauft / aktiviert werden. Alle übrigen Gutscheinarten von E-Guma können nur über die Kasse eingelöst werden. Die Liste der gültigen Gutscheinnummern wird entweder als PDF oder als Excel-Datei bei der Gutscheinanlage in E-Guma zur Verfügung gestellt.
Um einen vordefinierten E-Guma Depot-Gutschein zu aktivieren, wählt man an der Touchkasse den Button für Gutscheinverkauf z.B. "Gutschein E-GUMA".
Nun gibt man die Gutscheinnummer lt. PDF oder Excelsheet ein und bestätigt mit <ENTER>. Das Einlesen des Gutscheincodes aus der PDF-Datei kann auch durch Lesen des Barcodes mittels Scanner erfolgen.
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Es ist auch möglich mehrere Gutschein hintereinander auf einem Beleg zu 'verkaufen'.
Nach Bestätigung der Eingabe wird der Gutschein auf Gültigkeit geprüft und kann abgerechnet werden. Sollte ein Gutschein nicht mehr aktivierbar sein, erhält man eine entsprechende Meldung.
Nach erfolgter Abrechnung wird der Gutschein über die Schnittstelle aktiviert und die Gültigkeit kann über Funktionen - Gutscheininfo abgefragt werden
Beispiel eines Verkaufbeleges mit mehreren Gutscheinen
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Verkaufsstorno / Deaktivieren von E-Guma - Gutscheinen
Durch das Stornieren eines Verkaufsbeleges in NovaTouch und Storno der Gutscheinbonierung wird auch die Aktivierung eines Depotgutscheines zurückgenommen:
Wird der Gutscheinartikel selbst nicht storniert, bleibt dieser aktiviert!
Nach dem Storno des aktivierten Gutscheines kann über die Gutscheininfo der aktuelle Status abgefragt werden und man sieht, dass dieser in E-Guma wieder auf 'nicht verkauft' zurückgesetzt wurde.
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Einlösung von E-Guma - Gutscheinen
Nach Auswahl der Zahlungsart 'Gutscheineinlösung' oder lesen des Barcodes mittels Scanner in der Zahlartauswahl erfolgt die Gültigkeitsprüfung des Gutscheines bei E-Guma. Ist der Gutschein gültig, so wird der Zahlungsbetrag vom Wert des Gutscheines abgezogen und die Rechnung abgeschlossen. Reicht der Gutscheinwert nicht aus, so muss man eine zusätzliche Zahlungsart auswählen, bevor die Rechnung abgeschlossen werden kann.
Auf dem Rechnungsbeleg wird unterhalb der Zahlungsart die verwendete Gutscheinnummer angedruckt.
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Werden bei der Abrechnung mehrere Gutscheine verwenden, so sind diese nacheinander durch Auswahl der Zahlungsart 'Gutscheineinlösung' und Eingabe der jeweiligen Gutscheinnummer zu hinterlegen
Einlösungsstorno von E-Guma - Gutscheinen
Wird eine mit Gutschein abgerechnete Rechnung wieder storniert, erfolgt eine automatische Rückbuchung des Gutscheinwertes bei E-Guma.
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Gutscheininfo abfragen
Über Funktionen - Information E-Guma-Schnittstelle kann man nach Eingabe der Gutscheinnummer den aktuellen Status eines Gutscheines ablesen:
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Das E-Guma Portal
Über das Portal können die Gutscheine angelegt und verwaltet werden. Detailinformationen zur Handhabung erhalten Sie durch den E-Guma Support oder die On-Line Hilfe von E-Guma
Bei der Anmeldung werden der Benutzername, das Kennwort und der Mandant benötigt:
In diesem Beispiel heißt der Benutzer 'Integration' und der Mandant 'beethoven palace'
Nach dem Drücker der 'Login'-Taste kommt man in die E-Guma Verwaltung.
Über den Menüpunkt Depot - Verwalten können neue Depotgutscheine angelegt werden, die dann über die NovaTouch POS verkauft/ aktiviert werden können.
In der letzten Spalte ist nach Anlage entweder ein Symbol für die PDF-Datei oder für die Excel-Datei vorhanden. Ein Klicken auf dieses Symbol ermöglicht den Download der jeweiligen Datei
NovaTouch – IFC zu E-GUMA
novacom software gmbh – Oppauerplatz 111 – A-8990 Bad Aussee
Bsp: PDF:
Hat man sich bei der Anlage für die Excel-Datei entschieden, erhält man eine Datei, die man z.B. an die Druckerei weiterleiten kann oder die Gutscheinnummern manuell in eigene Gutscheinformulare überträgt (z.B. Serienbrief in Word).
Die 1. Spalte enthält den Gutscheincode unformatiert, die 2. Spalte enthält den formatierten Gutschein-Code, zur besseren Lesbarkeit in 4er Gruppen getrennt.
Die Schnittstelle von NovaTouch zu E-Guma kann mit beiden Werten eine Gutscheinanfrage an E-Guma absetzen und verarbeiten.