Resumen de los pasos necesarios para poner en marcha un cliente:

1. Creación de la estructura organizativa
2. Configuración
3. Establecimiento de la conexión a la Cloud
4. Inicialización del cliente

1. Creación de la estructura organizativa

Como primer paso para la puesta en marcha, es necesario crear primero la estructura organizativa de la empresa operadora de las cajas registradoras en RetailForce Cloud. Encontrará más detalles al respecto en el artículo enlazado.

Este paso puede omitirse en el caso de los sistemas que deban funcionar completamente sin conexión y que no establezcan conexión con RetailForce Cloud en ningún momento.

2. Configuración

La configuración de un cliente de middleware puede realizarse básicamente de dos formas diferentes (dependiendo de los ajustes y acuerdos establecidos por el fabricante del software de caja registradora y la empresa operadora de la caja registradora):

1. Configuración a través de RetailForce Cloud o, alternativamente
2. Configuración a través del software de punto de venta (sistema de caja registradora, sistema de registro electrónico)

1. Configuración a través de RetailForce Cloud

En esta variante, el cliente descarga localmente un objeto de configuración preparado en RetailForce Cloud. Esto puede considerarse una configuración automática. La creación de objetos de configuración se describe en el artículo enlazado.

Al configurar una unidad fiscal a través de la Cloud, todos los datos que requiere el sistema ya están preconfigurados en la Cloud (instrucciones e información general sobre la creación de una configuración). Estos datos se cargan desde la Cloud mediante una llamada desde el client fiscal (CreateClientByCloud).

Los parámetros de la llamada son:

• Identificación de la empresa (companyIdentification), normalmente el número de identificación fiscal (VatNumber). Dependiendo del país de tributación, puede ser necesario introducir otras características de identificación de forma alternativa o adicional (!). No obstante, se recomienda el número de identificación fiscal para la puesta en marcha.
• Número de tienda o sucursal
• Número de caja registradora
• cloudApiKey
• cloudApiSecret

Si la función PUT api/v1/management/clients/byCloud se completa sin errores, la configuración del cliente fiscal habrá finalizado. El GUID del módulo fiscal (=clientId) se transmite como valor de retorno.

2. Configuración a través del software de punto de venta

Como alternativa a la configuración automática del cliente a través del RetailForce Cloud system, el objeto de configuración también puede prepararse mediante el software de TPV. Este tipo de configuración se utiliza para sistemas que no disponen de conexión con RetailForce Cloud. Para ello se utiliza el punto final PUT /api/v1/management/clients.

Al configurar el software de caja registradora, existen dos formas de poner en marcha el módulo correctamente:

1. Módulo sin conexión a la Cloud, con almacenamiento y exportación de datos locales
2. Módulo con conexión a la Cloud, con almacenamiento y exportación de datos tanto locales como en la Cloud

En cualquier caso, es necesario que los parámetros de configuración necesarios se establezcan correctamente de acuerdo con la documentación.

La variante 2 (con conexión a la Cloud) puede activarse posteriormente; es decir, es posible crear una configuración fiscal sin conexión a la Cloud y, a continuación, sincronizarla con la Cloud.

Cabe señalar que la creación de un client en la Cloud debe estar habilitada por el fabricante del software de punto de venta y/o por la organización en la configuración de la Cloud. El procedimiento estándar consiste en crear primero un objeto de configuración en la Cloud.

3. Establecimiento de la conexión a la Cloud

El siguiente paso consiste en conectar el client a RetailForce Cloud (en el caso de los sistemas sin conexión a la nube, este paso puede omitirse). Esto se realiza mediante la función:

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

Parámetros de la llamada:

• clientId: el ID único del cliente (GUID) que se facilitó a la caja registradora al configurarla a través de RetailForce Cloud.
• cloudApiKey
• cloudApiSecret

4. Inicialización del cliente

Al llamar a la función InitializeClient (POST /api/v1/management/clients/initialize), con el parámetro (documento de inicio), se invoca la rutina de inicialización del país correspondiente; en este proceso también se inicializan los componentes de seguridad (si es necesario).
Para cuestiones específicas de cada país o de hardware, consulte la documentación pertinente.

El documento de inicio puede solicitarse al servicio ejecutando la función:

• GET /api/v1/transactions/document/{clientId}/start
  (parámetro: clientId, opcional: BookDate).

Si se utiliza FiscalClient sin fiscalización (NoFiscalisation), por ejemplo, cuando únicamente se transmiten al cliente recibos digitales o datos de archivo, no es necesaria la inicialización.

• Llamada a la función de inicialización (InitializeClient - POST /api/v1/management/clients/initialize)

A continuación, la inicialización de la unidad fiscal se lleva a cabo mediante la llamada InitializeClient.

Se pasa un NullReceipt a la función InitializeClient; a continuación se muestra un ejemplo:

{
    "modelVersion": "1.5.2",
    "uniqueClientId": "c1062c55-57c4-4ed2-9c53-aff1762326a4",
    "additionalFields": {},
    "documentGuid": "5efa5306-fe53-452d-9c81-68329475eee0",
    "documentId": "1",
    "createDate": "2025-05-02T07:08:17.8334419+02:00",
    "bookDate": "2025-05-02T07:08:17.8335535+02:00",
    "documentNumber": "1",
    "documentType": 1000,
    "documentTypeCaption": "Startbeleg",
    "user": {
        "id": "1",
        "caption": "User 1",
        "firstName": "1",
        "lastName": "User",
        "dateOfEntry": "2025-05-02T07:08:17.833596+02:00"
    },
    "allocationGroups": [],
    "positionCount": 0,
    "fiscalDocumentNumber": 1,            
    "fiscalDocumentRevision": 1,          
    "positions": [],
    "Payments": [],
    "additionalHeader": [],
    "additionalFooter": [],
    "fiscalAdditionalFields": {}
}

El proceso de inicialización varía según el país, pero la llamada al método es la misma para todos los países. Para obtener más detalles sobre las inicializaciones específicas de cada país, consulte la documentación correspondiente a cada país.

Puesta en marcha de un vistazo

Para poner en marcha un cliente, se invocan las siguientes funciones en el orden indicado:

Artículos relacionados

Inicialización en Alemania

Gestión de errores

Error: No se ha encontrado GetConfiguration para el cliente <clientid></clientid>

Este artículo ha sido traducido automáticamente.