Overview of the steps required to commission a client:

1. Creating Organisational Structure
2. Configuration
3. Establishing Cloud Connection
4. Client initialisation

1. Creating Organisational Structure

As a first step towards commissioning, the organisational structure of the cash register-operating company must first be created in the RetailForce Cloud. You can find details on this in the linked article.

This step can be skipped for systems that should work completely offline and do not establish a connection to the RetailForce Cloud at any time.

2. Configuration

The configuration of a Fiscal Middleware client can basically be done in two different ways (depending on the settings and agreements made by the cash register software manufacturer and the cash register operating company):

1. Configuration via RetailForce Cloud, or alternatively
2. Configuration via POS software (cash register system, electronic recording system)

1. Configuration via RetailForce Cloud

In this variant, the client downloads a configuration object prepared in the RetailForce Cloud locally. This can be regarded as an automatic configuration. The creation of configuration objects is described in the linked article.

When configuring a fiscal unit through the cloud, all the data required by the system is already configured in the cloud (instructions and general information on creating a configuration). This data is loaded from the Cloud by means of a call from the fiscal client (CreateClientByCloud).

Parameters for the call are:

• Company identification (CompanyIdentification), usually the VAT identification number (VatNumber). Depending on the tax country, it may be necessary to enter other ID characteristics alternatively or additionally (!). However, the VAT ID number is recommended for the start-up.
• Store / Branch number
• Cash register number
• cloudApiKey
• cloudApiSecret

If the function PUT api/v1/management/clients/byCloud is completed without error, the configuration of the fiscal client is finished. The Guid of the fiscal module (=clientId) is transmitted as a return value.

2. Configuration via POS software

As an alternative to automatic client configuration via the RetailForce Cloud system, the configuration object can also be prepared by the POS software. This type of configuration is used for systems that do not have a connection to the RetailForce Cloud. The endpoint PUT /api/v1/management/clients is used for this.

When configuring the cash register software, there are 2 ways to start up the module correctly:

1. Module without cloud connection with local data storage and export
2. Module with cloud connection with local and cloud data storage and export

In any case, it is necessary that the necessary configuration parameters are set correctly according to the documentation.

Variant 2 (with cloud connection) can also be activated later, i.e. it is possible to create a fiscal configuration without cloud connection and then synchronise it with the cloud.

It should be noted that the creation of a client in the cloud must be enabled by the POS software manufacturer and/or the organisation in the cloud settings. The standard way is to first create a configuration object in the cloud.

3. Establishing Cloud Connection

The next step is to connect the client to the RetailForce Cloud (for offline systems, without a cloud connection, this step can be skipped). This is done via the function:

• POST /api/v1/management/cloud/connect.

Parameters for the call:

• clientId - the unique client ID (Guid) was returned to the cash register when configured via RetailForce Cloud.
• cloudApiKey
• cloudApiSecret

4. Client initialisation

By calling the function InitializeClient (POST /api/v1/management/clients/initialize), with parameter (start document), the initialisation routine of the respective country is called, any security components are also initialised in this process (if necessary).
For country and or hardware-specific topics, please refer to the relevant documentation.

The start document can be requested from the service by executing the function:

• GET /api/v1/transactions/document/{clientId}/start
  (parameter: clientId, optional: bookDate).

If the FiscalClient is used without fiscalisation (NoFiscalisation), for example if only digital receipts or archive data are transmitted to the client, initialisation is not necessary.

• Calling the Initialisation Function (InitializeClient - POST /api/v1/management/clients/initialize)

The initialisation of the fiscal unit is then carried out by means of the call InitializeClient.

A NullReceipt is passed to the InitializeClient function, an example can be found below:

{
    "UniqueClientId": "c1062c55-57c4-4ed2-9c53-aff1762326a4",
    "DocumentGuid": "5efa5306-fe53-452d-9c81-68329475eee0",
    "DocumentId": "5efa5306-fe53-452d-9c81-68329475eee0",
    "CreateDate": "2021-02-02T05:31:08.9450964+01:00",
    "BookDate": "2021-02-02T05:31:08.9450964+01:00",
    "DocumentNumber": null,
    "CancellationDocument": false,
    "DocumentReference": null,
    "IsTraining": false,
    "DocumentType": 1000,
    "DocumentTypeCaption": null,
    "User": {
        "Id": "1234",
        "Caption": "Testuser"
    },
    "AllocationGroups": [],
    "Partner": null,
    "FiscalResponse": null,               
    "FiscalDocumentNumber": 1,            
    "FiscalDocumentRevision": 1,          
    "Positions": [],
    "Payments": []
}

The initialisation process is basically country-specific, but the call remains the same for all countries. For details on the country-specific initialisations, please refer to the respective country documentation.

Commissioning at a glance

The following functions are called up in the present order to commission a client:

Related articles

Initialization Germany

Error handling

Error: GetConfiguration for client <ClientId> not found