A RetailForce desenvolve software para cumprir os regulamentos relativos à fiscalização de sistemas de registo eletrónico em diferentes países. Este software denomina-se «Fiscal Middleware».

O presente documento fornece uma visão geral sobre como integrar o RetailForce Middleware. A arquitetura do sistema a montante que envia e recebe dados do RetailForce Middleware, bem como os requisitos e funções específicos deste sistema, podem tornar necessário desviar-se desta descrição.

1. Noções básicas

A seguir, são enumerados os passos individuais que devem ser realizados antes de iniciar a integração. Estes passos são também abordados em pormenor durante a sessão de integração.

1.1 Visão geral das variantes de integração

Antes de iniciar a integração, obtenha uma visão geral das diferentes variantes de integração disponíveis. Estas variantes são descritas no artigo seguinte: Visão geral da fiscalização com o RetailForce – RetailForce Software GmbH (=artigo de visão geral).

As fontes a partir das quais pode descarregar o RetailForce Middleware nas diferentes variantes também se encontram no artigo referenciado.

Após ter descarregado o Fiscal Middleware, proceda à instalação. Encontrará uma descrição de como instalar as diferentes variantes no artigo de visão geral.

1.1.1 Online vs. Offline

O RetailForce Middleware é, essencialmente, um sistema de software autónomo. No entanto, várias funções só estão disponíveis quando o middleware está ligado à RetailForce Cloud.

A RetailForce Cloud disponibiliza várias funções de gestão, tais como a configuração remota automática do middleware, incluindo a atribuição de licenças, bem como funções de arquivo seguro a longo prazo.

Para utilizar as funções da RetailForce Cloud, o Fiscal Middleware ou o cliente específico da instalação (cliente = instância única do sistema de registo eletrónico) deve estar ligado a um terminal na RetailForce Cloud.

Caso o middleware venha a ser utilizado sem estabelecer uma ligação à Cloud (sistema offline), os passos seguintes podem ser ignorados. Prossiga com o ponto 1.5.

Nota: Recomendamos o estabelecimento de uma ligação à Cloud (= sistema online), uma vez que isto simplifica consideravelmente a colocação em funcionamento de um client e permite a automatização da inicialização de qualquer hardware necessário.

1.2 Aceder ao RetailForce portal

Todas as funções da RetailForce Cloud são disponibilizadas através

o RetailForce Cloud Portal (https://portal.retailforce.cloud), bem como através da
Cloud API (https://api.retailforce.cloud/swagger)

O auto-registo no RetailForce portal não é possível por motivos de segurança. Para obter acesso ao portal, deve receber um link de convite de um utilizador já autorizado. O processo de registo subsequente é descrito no artigo seguinte: Registo no RetailForce portal – RetailForce Software GmbH.

1.3 Estrutura Organizacional

É necessário criar primeiro uma estrutura organizacional no portal. O artigo «Criação de uma estrutura organizacional no RetailForce Cloud – RetailForce Software GmbH» fornece uma visão geral das funções disponíveis para este efeito.

1.4 Configuração

Após a criação da estrutura organizacional, de, pelo menos, uma organização (=cliente), uma loja (=sucursal) e um terminal (=caixa), deve ser preparado um objeto de configuração na Cloud e atribuído a uma entidade (organização, empresa, loja ou terminal). Pode encontrar uma descrição deste processo em: Informações gerais sobre a configuração – RetailForce Software GmbH.

1.5 Inicialização

Se os passos anteriores tiverem sido executados com sucesso, o Fiscal Middleware pode ser colocado em funcionamento. Os passos necessários para a colocação em funcionamento (com e sem o estabelecimento da ligação à Cloud) são explicados mais detalhadamente no artigo Inicialização (geral) – RetailForce Software GmbH.

Nota: Tenha em atenção que, no artigo acima referido, os processos «Criar estrutura organizacional » e «Criar configuração » também são descritos novamente.

Como resultado do processo de colocação em funcionamento/inicialização, o Fiscal Client deverá

estar totalmente configurado,
- quer através de um objeto de configuração preparado na Cloud, quer
- «manualmente» pelo sistema de registo eletrónico,
e dispor de um ID de cliente único.

2. Integração

Após a conclusão bem-sucedida da ativação de um client («caixa registadora»), a integração pode ser iniciada.

Esta secção fornece orientações sobre o processo de transferência de documentos entre a caixa registadora (sistema de registo eletrónico) e o client específico.

2.1 Serviço Web REST

O artigo seguinte ajuda a dar os primeiros passos na integração da interface do serviço Web REST, que é utilizada para

o serviço do Windows, bem como
o contentor Docker.

Primeiros passos com o serviço fiscal – RetailForce Software GmbH

2.2 Implementação do NuGet

A ajuda para a implementação nuget (DLL) do middleware é fornecida no artigo seguinte: Primeiros passos na implementação nuget – RetailForce Software GmbH.

2.3 Interface do sistema de ficheiros

Para além das duas variantes de implementação acima mencionadas, o serviço web REST e o nuget, o middleware também pode ser acedido através de uma interface de ficheiros. Encontrará mais informações sobre este assunto no artigo: Interface do sistema de ficheiros – RetailForce Software GmbH.

Nota: Tenha em atenção que a interface de ficheiros não está disponível em todos os países! Além disso, recomendamos a utilização da interface de ficheiros apenas se, por motivos técnicos, a implementação através do serviço web REST e do nuget não for possível.

2.4 Processo de transmissão de documentos

Após a instalação do Fiscal Middleware, que funciona de forma semelhante a um serviço do Windows, num computador, a descrição da api pode ser acedida através de http://localhost:7678/swagger/index.html.

No caso de instalação num computador remoto (por exemplo, numa LAN), utilize o endereço IP do sistema no qual o middleware foi instalado, em vez de «localhost».

Todos os pontos finais do middleware estão descritos no swagger. Para a transmissão de documentos (por exemplo, recibos de caixa), são importantes os pontos finais da secção «Transações».

A transmissão de documentos é sempre um processo em duas etapas, que é iniciado com

«createDocument» e termina com
«storeDocument» ou com «cancelDocument», no caso de cancelamento do documento.

O processo de transmissão de documentos é explicado em pormenor aqui: Processo básico de transferência de documentos – RetailForce Software GmbH.

2.5 Fiscal Service Client Sample

RetailForce disponibiliza um programa de exemplo, o Fiscal Service Client Sample. Este fornece orientações sobre como criar a estrutura JSON na qual os documentos são enviados para o Serviço Fiscal.

O Fiscal Service Client Sample pode ser utilizado para gerar exemplos de diferentes tipos de documentos e casos de negócio.

Pode encontrar uma descrição do programa em: Fiscal Service Client Sample – RetailForce Software GmbH.

Também pode encontrar exemplos de diferentes documentos e casos de negócio no Centro de Soluções em: Transações comerciais – RetailForce Software GmbH.

Nota: Tenha em atenção que os casos de negócio aqui enumerados podem basear-se num modelo de documento mais antigo. Recomendamos a utilização do Fiscal Service Client Sample.

2.6 Lista de pontos de extremidade

A seguir, são descritos os pontos finais que devem ser implementados em qualquer caso.

Ponto de extremidade	Descrição
PUT /api/va/management/clients	apenas necessário se a configuração do client for efetuada a partir do software de PDV e não a partir do sistema na nuvem. Alternativa: PUT /api/v1/management/clients/byCloud
PUT /api/v1/management/clients/byCloud	necessário se a configuração do client for efetuada a partir do sistema na Cloud. Alternativa: PUT /api/va/management/clients
POST /api/v1/management/cloud/connect	estabelece a ligação à nuvem de um cliente. Deve ser efetuado após cada reinício do computador (sistema). Os dados necessários para estabelecer a ligação à nuvem (chave API e API Secret) devem ser armazenados pelo sistema de registo eletrónico.
POST /api/v1/management/clients/initialize	Inicializa o cliente ou qualquer hardware fiscal necessário (dispositivo técnico de segurança, unidade de criação de assinatura, impressora, etc.). É necessário um documento de início para a inicialização. Este pode ser gerado pelo sistema de registo eletrónico ou automaticamente através do middleware com o ponto de extremidade GET /api/v1/transactions/document/{clientId}/start.
GET /api/v1/transactions/document/{clientId}/start	Recomendado. Cria o chamado documento de início para o client específico, para efeitos de inicialização.
PUT /api/v1/transactions/createDocument	Este método não cria, por si só, um documento; limita-se a iniciar o processo, por exemplo, no TSE (Dispositivo Técnico de Segurança) na Alemanha. (Obrigatório em todos os países!)
POST /api/v1/transactions/storeDocument	Guarda o documento em questão
POST /api/v1/transactions/cancelDocument	Cancela um documento na unidade de fiscalização.

Este artigo foi traduzido automaticamente.

Orientações de implementação

1. Noções básicas

1.1 Visão geral das variantes de integração

1.1.1 Online vs. Offline

1.2 Aceder ao RetailForce portal

1.3 Estrutura Organizacional

1.4 Configuração

1.5 Inicialização

2. Integração

2.1 Serviço Web REST

2.2 Implementação do NuGet

2.3 Interface do sistema de ficheiros

2.4 Processo de transmissão de documentos

2.5 Fiscal Service Client Sample

2.6 Lista de pontos de extremidade

Comentários

1. Noções básicas

1.1 Visão geral das variantes de integração

1.1.1 Online vs. Offline

1.2 Aceder ao RetailForce portal

1.3 Estrutura Organizacional

1.4 Configuração

1.5 Inicialização

2. Integração

2.1 Serviço Web REST

2.2 Implementação do NuGet

2.3 Interface do sistema de ficheiros

2.4 Processo de transmissão de documentos

2.5 Fiscal Service Client Sample

2.6 Lista de pontos de extremidade

Artigos relacionados