01. DADOS GERAIS
| Produto: | TOTVS Logística Recintos Aduaneiros
|
|---|---|
| Linha de Produto: | Linha Logix |
| Segmento: | Logística |
| Módulo: | Serviço de Integração TPD - Recintos Aduaneiros |
| Função: | Serviço de Integração TPD - Recintos Aduaneiros |
| Ticket: | |
| Requisito/Story/Issue (informe o requisito relacionado) : |
02. SITUAÇÃO/REQUISITO
Para atendimento à solicitação para resolução de problemas relacionados à conexão com balanças rodoviárias, com comunicação efetuada através dos protocolos TCP/IP, em que duas ou mais estações, utilizando o módulo Portaria, tentam conectar-se simultaneamente à mesma balança, causando erro de conexão, foi elaborada a solução de integração para conexão entre as estações e as balanças configuradas.
A conexão, por dar-se através de sockets TCP/IP, causa erro de conexão por tratar-se de canal exclusivo de comunicação, não aceitando que dois ou mais canais sejam abertos simultaneamente. Mesmo que não haja a necessidade de duas ou mais estações acessarem a mesma balança simultaneamente, o problema pode ocorrer no momento em que o operador execute o processo de alteração da balança a ser acessada, uma vez que isso pode efetuar uma tentativa de conexão com uma balança já conectada a uma estação.
03. SOLUÇÃO
A solução, uma aplicação no modelo de serviço para o sistema Microsoft Windows, deve ser instalada em um servidor na infraestrutura local de rede, uma vez que, para garantir a estabilidade da comunicação desta com as balanças, a latência de rede deve ser a menor possível. Sendo assim, esta solução não está homologada para operação em nuvem, sendo vetada integralmente sua utilização em tal modelo.
Para tanto, as soluções dependem de requisitos a serem atendidos anteriormente e que podem ser vistos a seguir. É importante salientar que, para um perfeito processo de integração, todos os requisitos adiante devem ser atendidos antes da implantação, garantindo o perfeito funcionamento da solução.
Já o processo de implantação, uma vez que todos os requisitos sejam atendidos, é simples e rápido. Se seguido conforme as instruções constantes neste artigo, a possibilidade de falha no processo de integração é praticamente nula.
- Sistema operacional Microsoft Windows Server 2012 ou superior e;
- 25MB de espaço em disco.
Para a instalação da solução, basta copiá-la para um diretório disponível no servidor alvo - como C:\TOTVS\SARA\Services\IntgraçãoBalanças, por exemplo - e comandar sua instalação através do comando abaixo, devendo ser executado por um usuário com privilégios administrativos:
C:\TOTVS\SARA\Services\IntgraçãoBalanças>TOTVSIntgBalanca.exe /install
É importante notar que a instalação pode ser parametrizada, fornecendo as configurações adequadas através de linha de comando, sendo:
| Parâmetro | Descrição | Exemplo |
|---|---|---|
| -h | Nome do servidor de banco de dados Microsoft SQL Server. | -hSERVIDORBD\SQLSERVER2019 |
| -p | Porta de comunicação com o servidor de banco de dados Microsoft SQL Server. | -p1433 |
| -d | Nome do banco de dados a ser utilizado. | -dsara_db |
| -u | Nome do usuário de banco de dados utilizado na conexão. | -usa |
| -P | Senha do usuário de banco de dados utilizado na conexão. | -PTotvs@123456 |
| -r | Porta de comunicação da API fornecida pelo serviço de integração. | -r4321 |
Sendo assim, um exemplo de instalação parametrizada via linha de comando seria:
C:\TOTVS\SARA\Services\IntgraçãoBalanças>TOTVSIntgBalanca.exe -hSERVIDORBD\SQLSERVER2019 -dsara_db -p1433 -usa -PTotvs@123456 -r9876 /install
NOTAS
- Quando a porta de comunicação da API fornecida pelo serviço de integração for escolhida no processo de instalação, a porta seguinte também deve estar livre, uma vez que a documentação Swagger da API será exibida através dela. Ex.: instalando o serviço com a porta 9876 para a API, a porta 9877 será disponibilizada para a documentação.
- Quando utilizando a versão legada do serviço, para que o novo serviço possa ser instalado, este deve ser parado e desativado no servidor afim de evitar a concorrência na conexão com as balanças integradas ou pelo consumo da porta de comunicação da API. Uma vez homologado o novo serviço, o serviço legado pode ser desinstalado por meio da linha de comando apropriada em um terminal com privilégios administrativos.
Após o término da instalação do serviço de integração - com a mensagem de sucesso sendo exibida pelo sistema operacional - é necessário realizar as configurações referentes ao serviço. Para isso, é necessário executar, com privilégios administrativos, o editor de registro do sistema Microsoft Windows, acessando a chave a seguir:
Computador\HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\TOTVSIntgBalanca
Esta chave apresenta todas as configurações do serviço junto ao servidor e deve conter três subchaves: API, Database e Log. Cada uma destas subchaves contém um subgrupo de configurações, os quais devem conter os seguintes valores:
| Subchave | Configuração | Função específica | Valor padrão | Padrão do valor a ser inserido |
|---|---|---|---|---|
| API | Audience | Valor de validação das restrições de uso da API de integração disponibilizada pelo serviço. | Integração Balanças | Nenhum |
| API | DSContext | Valor de configuração da rota de acesso à API de integração disponibilizada pelo serviço. | api/ | ^[a-z0-9_]+\/$ |
| API | Issuer | Valor de validação das restrições de uso da API de integração disponibilizada pelo serviço. | SARA | Nenhum |
| API | Port | Porta TCP pela qual o serviço fará a exposição de sua API. | 4321 | 1~65535 |
| API | RESTContext | Valor de configuração da rota de acesso à API de integração disponibilizada pelo serviço. | sara/ | ^[a-z0-9_]+\/$ |
| Database | CharSet | Conjunto de caracteres utilizado pelo servidor Microsoft SQL Server. | SQL_Latin1_General_CP1_CI_AS | Nenhum |
| Database | Database | Nome do banco de dados usado pelo ecossistema TOTVS Recintos Aduaneiros. | sara_db | Nenhum |
| Database | DriverID | Identificação do tipo de banco de dados a ser utilizado. | MSSQL | Nenhum |
| Database | Hostname | Indicação de localização do servidor Microsoft SQL Server. | localhost | NomeDoServidor\NomeDaInstância |
| Database | Password | Senha do usuário usado na integração para acesso ao banco de dados. | Totvs@123 | Nenhum |
| Database | Port | Porta padrão de comunicação do servidor Microsoft SQL Server. | 1433 | 1~65535 |
| Database | Username | Nome do usuário usado na integração para acesso ao banco de dados. | sa | Nenhum |
| Log | LogFile | Caminho completo para o arquivo de log da aplicação. | C:\Temp\TOTVS\IntgBalanca\IntgBalanca_%s.log | ^[A-Z]{1}:\\([\w]+\\)+(IntgBalanca_%s\.log)$ |
| Log | WithDetailLog | Indicativo para registros de log detalhados. | false | true/false |
Após efetuada a configuração dos parâmetros de operação do serviço, basta acessar o gestor de serviços do servidor e comandar sua inicialização.
Ao instalar e iniciar o serviço de integração com balanças com comunicação via TCP/IP, este fornecerá um canal para acesso à sua documentação OpenAPI através da ferramenta Swagger inclusa no serviço. Conforme exemplo citado na seção de instalação, o serviço tendo sido instalado em um servidor cujo endereço IP seja 172.26.224.1 e a porta de comunicação seja 9876, o acesso à documentação se dá pela URL http://172.26.224.1:9877/docs, exibindo-a conforme visto abaixo:
Esta documentação permite que as respostas da API sejam testadas e validadas de forma rápida e simples. Contudo, os endpoints que contem com o parâmetro token, seja na URI - {token} - ou em seu corpo - nó token no objeto JSON passado na mensagem -, este não pode ser gerado senão pela equipe TOTVS durante o atendimento e os mesmos terão validade, máxima, de 30 minutos.
04. DEMAIS INFORMAÇÕES
Para uma perfeita integração com o sistema TOTVS Recintos Aduaneiros, este deve estar em sua versão 12.1.2301 ou superior, uma vez que esta versão está preparada para a integração com o sistema de integração com balanças rodoviárias e de armazém com comunicação via protocolo TCP/IP. Em versões anteriores a esta, a tentativa de integração ocasionará falhas no processo de integração que podem paralisar o serviço de integração e, na pior das hipóteses, paralisar o servidor onde ele esteja abrigado.
A configuração das balanças a serem integradas por meio deste serviço deve ter seu parâmetro Comunicação alterado para SERVIÇO INTEGRAÇÃO, de modo a permitir que o serviço as reconheça e estabeleça a comunicação. Os módulos Operacional e Portaria contam com cadastros distintos para balanças de armazém e rodoviárias, respectivamente, devendo as balanças integradas serem configuradas individualmente.
05. NOTAS
- Para o devido funcionamento de leitura das informações disponibilizadas pela balança, a mesma deve enviar os valores de leitura de forma íntegra, com seu buffer contendo integralidade da medição. Para mais informações sobre esta configuração, verifique o manual do equipamento.
- Esta solução é recomendada para ambientes em que haja concorrência na leitura do peso aferido em uma balança. Caso não haja necessidade, recomenda-se a configuração da balança como TCP-IP.
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas