Zum Hauptinhalt gehen

Implementierungsleitfaden

Harald Krondorfer
  • Aktualisiert

RetailForce entwickelt Software, um die Vorschriften zur Fiskalisierung von elektronischen Aufzeichnungssystemen in verschiedenen Ländern zu erfüllen. Diese Software wird "Fiscal Middleware" genannt. 

Dieses Dokument gibt einen Überblick über die Integration der RetailForce Fiscal Middleware. Die Systemarchitektur des vorgelagerten Systems, das Daten an die Fiscal Middleware sendet und von ihr empfängt, sowie spezielle Anforderungen und Funktionen dieses Systems können Abweichungen von dieser Beschreibung erforderlich machen.

1. Basics

Im Folgenden werden einzelne Schritte aufgeführt, die vor dem Start der Integration durchgeführt werden müssen. Diese Schritte werden auch im Rahmen des Onboardings im Detail besprochen.

1.1 Übersicht Integrationsvarianten

Bevor Sie mit der Integration beginnen, verschaffen Sie sich einen Überblick, über die unterschiedlichen Integrations-Varianten, welche zur Verfügung stehen. Diese Varianten werden im folgenden Artikel beschrieben: Übersicht Fiskalisierung mit RetailForce – RetailForce Software GmbH (=Übersichtsartikel).

Die Quellen, von welchen Sie die RetailForce Fiskal Middleware in den unterschiedlichen Varianten herunterladen können, finden Sie ebenfalls im verlinkten Artikel.

Nachdem Sie die Fiskal Middleware heruntergeladen haben, führen Sie die Installation durch. Eine Beschreibung, wie die Installation der unterschiedlichen Varianten erfolgt, finden Sie im Übersichtsartikel.

1.1.1 Online vs. Offline

Die RetailForce Fiskal Middleware ist grundsätzlich ein eigenständiges Softwaresystem. Verschiedene Funktionen stehen allerdings nur zur Verfügung, wenn die Middleware mit der RetailForce Cloud verbunden wird.

Die RetailForce Cloud stellt diverse Verwaltungsfunktionen, wie etwa die automatische Remote-Konfiguration der Middleware, inkl. Zuweisung von Lizenzen, sowie sichere Langzeitarchivierungsfunktionen zur Verfügung.

Um die Funktionen der RetailForce Cloud nutzen zu können, muss die Fiskal Middleware bzw. der spezifische Client innerhalb der Installation (Client = einzelne Instanz des elektronischen Aufzeichnungssystems) mit einem Terminal in der RetailForce Cloud verbunden werden.

Soll die Middleware ohne Herstellung einer Cloudverbindung (Offline-System) betrieben werden, kann der Nachfolgende Schritt übersprungen werden. Fahren Sie mit Punkt 1.5 fort. 

Hinweis: Wir empfehlen die Konfiguration über die RetailForce Cloud (= Online-System), da dies die Inbetriebnahme eines Clients erheblich vereinfacht und eine Automatisierung bei der Initialisierung der notwendigen Hardware ermöglicht.

1.2 Zugriff RetailForce Portal

Alle Funktionen der RetailForce Cloud werden sowohl über:

Eine Selbstregistrierung im RetailForce Portal ist aus Sicherheitsgründen nicht möglich. Um Zugriff auf das Portal zu erlangen, müssen Sie von einem bereits berechtigten Benutzer einen Einladungs-Link erhalten. Der daran anschließende Registrierungsprozess ist im folgenden Artikel beschrieben. Registrierung im RetailForce Portal – RetailForce Software GmbH.

1.3 Organisationsstruktur

Im Portal muss zunächst eine Organisationsstruktur angelegt werden. Der Artikel Anlage Organisationsstruktur RetailForce Cloud – RetailForce Software GmbH bietet eine Übersicht, welche Funktionen hierfür bereitgestellt werden.

1.4 Konfiguration

Nachdem die Organisationsstruktur, mindestens eine Organisation (=Kunde), ein Store (=Filiale), sowie ein Terminal (=Kasse) angelegt wurde, muss ein Konfigurationsobjekt in der Cloud vorbereitet und einer Entität (Organisation, Company, Store oder Terminal) zugeordnet werden. Eine Beschreibung für diesen Vorgang finden Sie unter: Allgemeine Information zur Konfiguration – RetailForce Software GmbH.

1.5 Inbetriebnahme

Wurden die vorhergehenden Schritte erfolgreich ausgeführt, kann eine Inbetriebnahme der Fiskal Middleware erfolgen. Die zur Inbetriebnahme erforderlichen Schritte (mit und ohne Herstellung der Cloud-Verbindung) wird im Artikel Inbetriebnahme (allgemein) – RetailForce Software GmbH näher erläutert.

Hinweis: Bitte beachten Sie, dass im obigen Artikel auch die bereits beschriebenen Prozesse "Anlegen Organisationsstruktur", sowie "Erstellung Konfiguration" nochmals angeführt werden.

Als Ergebnis der Inbetriebnahme sollte der Fiskal Client

  • fertig konfiguriert sein, entweder
    • durch ein in der Cloud vorbereitetes Konfigurationsobjekt oder
    • "manuell" durch das elektronische Aufzeichnungssystem, sowie
  • eine eindeutige Client-ID besitzen..

2. Integration

Nachdem die Inbetriebnahme eines Clients ("Kasse") erfolgreich abgeschlossen wurde, kann die Integration gestartet werden.

In diesem Abschnitt finden Sie Hinweise zum Prozess der Dokumentenübertragung zwischen Kasse (elektronischen Aufzeichnungssystem) und dem spezifischen Client.

2.1 REST Webservice

Der folgende Artikel hilft beim Einstieg in die Integration der REST-Webservice-Schnittstelle, welche für die Inbetriebnahme

  • des Windows Services sowie
  • des Docker Containers

verwendet wird:

Erste Schritte mit dem Fiskalservice – RetailForce Software GmbH

2.2 nutet Implementierung

Hilfe zur nuget (DLL-) Implementierung der Middleware bietet der folgende Artikel: Erste Schritte in der nuget Implementierung – RetailForce Software GmbH.

2.3 Dateischnittstelle

Neben den beiden oben genannten Implementierungsvarianten, REST-Webservice und nuget, kann die Middleware auch über eine Dateischnittstelle angesprochen werden. Finden Sie dazu mehr Informationen im Artikel: Dateischnittstelle – RetailForce Software GmbH.

Hinweis: Bitte beachten Sie, dass die Dateischnittstelle nicht für jedes Land zur Verfügung steht! Darüber hinaus empfehlen wir den Einsatz der Dateischnitt nur, wenn aus technischen Gründen keine Implementierung über REST-Webservice und nuget erfolgenden kann.

2.4 Dokumentenübermittlung Prozess

Nachdem die Fiskal Middleware, etwas im Form des Windows Dienstes, auf einem Rechner installiert wurde. Kann die API-Beschreibung über http://localhost:7678/swagger/index.html aufgerufen werden.

Im Falle einer Installation auf einem entfernten Rechner (z.B. LAN), verwenden Sie die IP-Adresse des Systems, auf welchem die Middleware installiert wurde, anstatt "localhost".

Im Swagger werden sämtliche Endpunkte der Middleware beschrieben. Wichtig für die Übertragung von Dokumenten, z.B. Kassenbelegen), sind die Endpunkte des Abschnittes "Transactions".

Die Dokumentenübermittlung ist immer ein zweistufiger Prozess, welcher mit

  1. "createDocument" gestartet und mit entweder
  2. "storeDocument" oder mit "cancelDocument", im Falle eines Belegabbruchs, abgeschlossen wird.

API-transactions.png

Der Prozess der Dokumentenübermittlung wird hier im Detail erläutert: Grundsätzlicher Prozess bei der Übertragung von Belegen – RetailForce Software GmbH.

2.5 Fiscal Service Client Sample

RetailForce bietet ein Beispielprogramm, das Fiscal Service Client Sample. Darin wird erläutert, wie die JSON-Struktur erstellt wird, in der die Dokumente an den Fiscal Service gesendet werden.

Mit dem Fiscal Service Client Sample können Beispiele für unterschiedliche Dokumententypen und Geschäftsfälle erzeugt werden.

Eine Beschreibung des Programmes finden Sie unter: Fiscal Service Client Sample – RetailForce Software GmbH.

Beispiele für unterschiedliche Dokumente und Geschäftsfälle finden Sie auch im Solution Center unter: Geschäftsfälle – RetailForce Software GmbH.

Hinweis: Bitte beachten Sie, dass die hier aufgeführten Geschäftsfälle auf einem älteren Dokumentenmodell basieren können. Wir empfehlen den Einsatz des Fiscal Service Client Samples.

2.6 Liste der Endpoints

Anschließend werden Endpunkte, welche jedenfalls implementiert werden sollten, beschrieben.

Endpoint Beschreibung
PUT /api/va/management/clients nur notwendig, wenn die Client-Konfiguration von der Kassensoftware und nicht aus dem Cloud-System heraus erfolgen soll. Alternativ PUT /api/v1/management/clients/byCloud
PUT /api/v1/management/clients/byCloud notwendig, wenn die Client-Konfiguration aus dem Cloud-System heraus erfolgen soll. Alternativ: PUT /api/va/management/clients
POST /api/v1/management/cloud/connect stellt die Cloud-Verbindung eines Clients her. Muss nach jedem Neustart des Rechners (Systems) erfolgen. Die zur Herstellung der Cloudverbindung notwendigen Daten (API Key und API Secret) müssen vom elektronischen Aufzeichnungssystem gespeichert werden.
POST /api/v1/management/clients/initialize Initialisiert den Client, bzw. eventuell notwendige Fiskalhardware (Technische Sicherheitseinrichtung, Signaturerstellungseinheit, Drucker, etc.). Zur Initialisierung wird ein Startbeleg benötigt. Dieser kann entweder vom elektronischen Aufzeichnungssystem oder automatisch über die Middleware, mit dem Endpunkt GET /api/v1/transactions/document/{clientId}/start erzeugt werden
GET /api/v1/transactions/document/{clientId}/start Empfohlen. Erzeugt einen so-genannten Startbeleg für den spezifischen Client, zur Initialisierung.
PUT /api/v1/transactions/createDocument Mit dieser Methode wird kein Dokument selbst erstellt, sondern nur der Prozess z.B. auf der TSE gestartet.
POST /api/v1/transactions/storeDocument Speichert das jeweilige Dokument
POST /api/v1/transactions/cancelDocument Storniert einen Beleg in der Fiskalisierungseinheit.

 

Verwandte Beiträge

Kommentare

0 Kommentare

Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.

Powered by Zendesk