PUT /api/v1/management/clients/ byCloud – RetailForce Software GmbH

This endpoint creates a new client in the Fiscal Middleware and links it to a terminal in the RetailForce Cloud. It represents the first step in the commissioning of a new till / cash register.

Results

A successful call of the endpoint (200)

creates a new client in the middleware, assigns it the uniqueClientId of the terminal (cloud) and
downloads the configuration object from the cloud system and configures the client accordingly.

Usage

One time, when a new cash register is put into operation. Calling the endpoint again for the same client (clientId) will result in an error!

ATTENTION: if a specific client has already been connected once to the terminal created in the cloud (assignment uniqueClientId), calling the endpoint again will result in an error message: "409 - Client already exists"). If a client has to be created again (e.g. hard disk failure, etc.), the endpoint /api/v1/management/clients/recovery/restoreByCloud must be used.

Prerequisites

Organisational structure and configuration object were created in the RetailForce Cloud and assigned accordingly
Fiscal Middleware installed

Form fields

The following information must be submitted:

Designation	Description	Example
Type	Type of company identification. The type must also have been entered and be present in the RetailForce Cloud. The following types are available: [0] = VatNumber, [1] = TaxNumber, [2] = GlnNumber, [3] = BusinessIdentificationNumber, [4] = Statistical classification, [5] = CommercialRegisterNumber, [6] = CommercialRegisterNumberOffice, [7] = TradeRegisterNumber See also: Company identification We recommend using type [0] = VatNumber as the primary ID in all countries (EU), even if it is not used as a mandatory company identifier in the respective country.	[0] = VatNumber
Identification	The company identification itself. Must match the information entered in the RetailForce Cloud.	ATU57780814
storeNumber	The number of the branch / store where the cash register is located. Must match the information entered in the RetailForce Cloud. ATTENTION: in France, the SIRET (extension of the SIREN by the branch number) must be indicated here.	S001, 12345 etc.
terminalNumber	Cash register number. Must match the information entered in the RetailForce Cloud.	0010
cloudApiKey	API Key to authenticate cloud communication	RFC_4a2abc...
cloudApiSecret	API Secret for authentication of cloud communication	ypts7u5OU...

Response

Possible responses:

Code	Description	Example
200	The client was successfully created and configured. The uniqueClientId is returned as the response object. The uniqueClientId must be saved by the POS system and used by the POS system for the entire further communication process (concerning the client).	3fa85f64-5717-4562-b3fc-2c963f66afa6
404	No organisation was found in the RetailForce Cloud for the specified company ID. Troubleshooting: Check company ID in RetailForce Cloud and at the cash register. Create company (organisation or company) in RetailForce Cloud	-
406	Due to the specified type (company code), no clear assignment is possible (e.g. when using [6] = CommercialRegisterNumberOffice). Troubleshooting: Use an different ID type (e.g. [0] = VatNumber)	-
409	There is already a client with the relevant uniqueClientId in the Fiscal Service (Fiscal Middleware). Troubleshooting: Use existing client	-