RetailForce develops Software to comply with regulations regarding fiscalisation of electronic recording system in different countries. This software is called “Fiscal Middleware”.
This document provides an overview of how to integrate the RetailForce Fiscal Middleware. The system architecture of the upstream system that sends data to and receives data from the Fiscal Middleware, as well as special requirements and functions of this system, may make it necessary to deviate from this description.
1. Basics
In the following, individual steps are listed which must be carried out before you start the integration. These steps are also discussed in detail during the onboarding session.
1.1 Overview on integrations variants
Before you start with the integration, get an overview of the different integration variants that are available. These variants are described in the following article: Overview Fiscalisation with RetailForce – RetailForce Software GmbH (=overview article).
The sources from which you can download the RetailForce Fiscal Middleware in the different variants can also be found in the linked article.
After you have downloaded the Fiscal Middleware, carry out the installation. A description of how to install the different variants can be found in the overview article.
1.1.1 Online vs. Offline
The RetailForce Fiscal Middleware is basically a stand-alone software system. However, various functions are only available when the middleware is connected to the RetailForce Cloud.
The RetailForce Cloud provides various management functions, such as automatic remote configuration of the middleware, including allocation of licences, as well as secure long-term archiving functions.
In order to use the functions of the RetailForce Cloud, the Fiscal Middleware or the specific client within the installation (client = single instance of the electronic recording system) must be connected to a terminal in the RetailForce Cloud.
If the middleware is to be operated without establishing a cloud connection (offline system), the following steps can be skipped. Continue with point 1.5.
1.2 Access RetailForce Portal
All functions of the RetailForce Cloud are provided via
- the RetailForce Cloud Portal (https://portal.retailforce.cloud) as well as via
- Cloud-API (https://api.retailforce.cloud/swagger)
Self-registration in the RetailForce portal is not possible for security reasons. To gain access to the portal, you must receive an invitation link from an already authorised user. The subsequent registration process is described in the following article: Registration in the RetailForce portal – RetailForce Software GmbH.
1.3 Organisational Structure
An organisational structure must first be created in the portal. The article Creating Organisational Structure in RetailForce Cloud – RetailForce Software GmbH provides an overview of which functions are provided for this purpose.
1.4 Configuration
After the organisational structure, at least one organisation (=customer), one store (=branch) and one terminal (=checkout) have been created, a configuration object must be prepared in the cloud and assigned to an entity (organisation, company, store or terminal). You can find a description of this process under: General information on configuration – RetailForce Software GmbH.
1.5 Initialization
If the previous steps have been carried out successfully, the Fiscal Middleware can be commissioned. The steps required for commissioning (with and without establishing the cloud connection) are explained in more detail in the article Initialization (general) – RetailForce Software GmbH.
As a result of the commissioning/initialization process, the Fiscal Client should
- be fully configured,
- either through a configuration object prepared in the cloud, or
- "manually" by the electronic record system,
- and have a unique client ID.
2. Integration
After the commissioning of a client ("cash register") has been successfully completed, the integration can be started.
This section provides guidance on the document transfer process between the cash register (electronic record system) and the specific client.
2.1 REST Webservice
The following article helps to get started with the integration of the REST web service interface, which is used for
- the Windows service as well as
- the Docker container.
First steps with fiscal service – RetailForce Software GmbH
2.2 nutet implementation
Help for the nuget (DLL-) implementation of the middleware is provided in the following article: First steps in nuget implementation – RetailForce Software GmbH.
2.3 File system interface
In addition to the two implementation variants mentioned above, REST web service and nuget, the middleware can also be addressed via a file interface. You can find more information about this in the article: File system interface – RetailForce Software GmbH.
2.4 Document transmission Process
After the Fiscal Middleware, somewhat in the form of the Windows service, has been installed on a computer. The API description can be accessed via http://localhost:7678/swagger/index.html.
In case of installation on a remote computer (e.g. LAN), use the IP address of the system on which the middleware was installed instead of "localhost".
All endpoints of the middleware are described in the swagger. Important for the transmission of documents (e.g. cash vouchers) are the endpoints of the section "Transactions".
Document transmission is always a two-step process, which is started with
- "createDocument" and ended with either
- "storeDocument" or with "cancelDocument", in case of document cancellation.
The document transmission process is explained in detail here: Basic document transfer process – RetailForce Software GmbH.
2.5 Fiscal Service Client Sample
RetailForce provides a sample programme, the Fiscal Service Client Sample. This provides guidance on how to create the JSON structure in which documents are sent to the Fiscal Service.
The Fiscal Service Client Sample can be used to generate examples of different document types and business cases.
A description of the programme can be found at: Fiscal Service Client Sample – RetailForce Software GmbH.
You can also find examples of different documents and business cases in the Solution Center at: Business transactions – RetailForce Software GmbH.
2.6 List of Endpoints
Subsequently, endpoints that should be implemented in any case are described.
| Endpoint | Description |
| PUT /api/va/management/clients | only necessary if the client configuration is to be done from the POS software and not from the cloud system. Alternative: PUT /api/v1/management/clients/byCloud |
| PUT /api/v1/management/clients/byCloud | necessary if the client configuration is to be done from the cloud system. Alternative: PUT /api/va/management/clients |
| POST /api/v1/management/cloud/connect | establishes the cloud connection of a client. Must be done after each restart of the computer (system). The data required to establish the cloud connection (API Key and API Secret) must be stored by the electronic recording system. |
| POST /api/v1/management/clients/initialize | Initialises the client or any necessary fiscal hardware (technical security device, signature creation unit, printer, etc.). A start document is required for initialisation. This can be generated either by the electronic recording system or automatically via the middleware with the endpoint GET /api/v1/transactions/document/{clientId}/start. |
| GET /api/v1/transactions/document/{clientId}/start | Recommended. Creates a so-called start document for the specific client, for initialisation. |
| PUT /api/v1/transactions/createDocument | This method does not create a document itself it just starts the process for instance on the TSE (Technical Security Device) in Germany. (Required in every country!) |
| POST /api/v1/transactions/storeDocument | Saves the respective document |
| POST /api/v1/transactions/cancelDocument | Cancels a document on the fiscalisation unit. |
Comments
0 comments
Please sign in to leave a comment.