Visão geral dos passos necessários para a colocação em funcionamento de um client:

1. Criação da estrutura organizacional
2. Configuração
3. Estabelecimento da ligação à Cloud
4. Inicialização do client

1. Criação da estrutura organizacional

Como primeiro passo para a entrada em funcionamento, a estrutura organizacional da empresa que opera as caixas registadoras deve ser criada na RetailForce Cloud. Pode encontrar mais detalhes sobre este assunto no artigo indicado na ligação.

Este passo pode ser ignorado no caso de sistemas que devem funcionar totalmente offline e que não estabeleçam, em momento algum, uma ligação à RetailForce Cloud.

2. Configuração

A configuração de um client do middleware fiscal pode, basicamente, ser efetuada de duas formas diferentes (dependendo das definições e acordos estabelecidos pelo fabricante do software de caixa registadora e pela empresa operadora das caixas registadoras):

1. Configuração através da RetailForce Cloud ou, em alternativa
2. Configuração através do software de PDV (sistema de caixa registadora, sistema de registo eletrónico)

1. Configuração através da RetailForce Cloud

Nesta variante, o client descarrega localmente um objeto de configuração preparado na RetailForce Cloud. Isto pode ser considerado uma configuração automática. A criação de objetos de configuração é descrita no artigo indicado na ligação.

Ao configurar uma unidade fiscal através da Cloud, todos os dados exigidos pelo sistema já se encontram configurados na Cloud (instruções e informações gerais sobre a criação de uma configuração). Estes dados são carregados a partir da Cloud por meio de uma chamada do client fiscal (CreateClientByCloud).

Os parâmetros para a chamada são:

• Identificação da empresa (companyIdentification), normalmente o número de identificação fiscal (VatNumber). Dependendo do país de tributação, poderá ser necessário introduzir outras características de identificação, em alternativa ou adicionalmente (!). No entanto, recomenda-se o número de identificação fiscal para a fase inicial.
• Número da loja/sucursal
• Número da caixa registadora
• cloudApiKey
• cloudApiSecret

Se a função PUT api/v1/management/clients/byCloud for concluída sem erros, a configuração do cliente fiscal está concluída. O GUID do módulo fiscal (=clientId) é transmitido como valor de retorno.

2. Configuração através do software de PDV

Como alternativa à configuração automática do cliente através do RetailForce Cloud system, o objeto de configuração também pode ser preparado pelo software de PDV. Este tipo de configuração é utilizado em sistemas que não dispõem de ligação à RetailForce Cloud. Para tal, é utilizado o ponto de extremidade PUT /api/v1/management/clients.

Ao configurar o software de caixa registadora, existem duas formas de iniciar corretamente o módulo:

1. Módulo sem ligação à Cloud, com armazenamento e exportação de dados locais
2. Módulo com ligação à Cloud, com armazenamento e exportação de dados locais e na Cloud

Em qualquer dos casos, é necessário que os parâmetros de configuração necessários sejam definidos corretamente, de acordo com a documentação.

A variante 2 (com ligação à Cloud) também pode ser ativada posteriormente, ou seja, é possível criar uma configuração fiscal sem ligação à Cloud e, posteriormente, sincronizá-la com a Cloud.

É de salientar que a criação de um client na Cloud deve ser ativada pelo fabricante do software de PDV e/ou pela organização nas definições da Cloud. O procedimento padrão consiste em criar primeiro um objeto de configuração na Cloud.

3. Estabelecer a ligação à Cloud

O passo seguinte consiste em ligar o client à RetailForce Cloud (no caso de sistemas offline, sem ligação à nuvem, este passo pode ser ignorado). Isto é feito através da função:

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

Parâmetros para a chamada:

• clientId — o ID único do cliente (Guid) que foi devolvido à caixa registadora quando configurado através da RetailForce Cloud.
• cloudApiKey
• cloudApiSecret

4. Inicialização do client

Ao chamar a função InitializeClient (POST /api/v1/management/clients/initialize), com o parâmetro (documento inicial), é acionada a rotina de inicialização do respetivo país; quaisquer componentes de segurança são igualmente inicializados neste processo (se necessário).
Para questões específicas do país e/ou do hardware, consulte a documentação relevante.

O documento inicial pode ser solicitado ao serviço através da execução da função:

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

Se o FiscalClient for utilizado sem fiscalização (NoFiscalisation), por exemplo, se apenas forem transmitidos ao client recibos digitais ou dados de arquivo, a inicialização não é necessária.

• Chamada da função de inicialização (InitializeClient - POST /api/v1/management/clients/initialize)

A inicialização da unidade fiscal é então efetuada através da chamada InitializeClient.

É passado um NullReceipt à função InitializeClient; pode encontrar um exemplo abaixo:

{
    "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": {}
}

O processo de inicialização é, basicamente, específico de cada país, mas a chamada permanece a mesma para todos os países. Para obter detalhes sobre as inicializações específicas de cada país, consulte a documentação do respetivo país.

Visão geral da colocação em funcionamento

As seguintes funções são chamadas na ordem apresentada para colocar um client em funcionamento:

Artigos relacionados

Inicialização na Alemanha

Tratamento de erros

Erro: GetConfiguration para o cliente <CLIENTID> não encontrado

Este artigo foi traduzido automaticamente.