Linha Microsiga Protheus

Árvore de páginas

CONTEÚDO


01. INTEGRAÇÃO ROTA INTELIGENTE

Cada vez mais é necessário pensar em soluções logísticas para otimizar e reduzir os custos das operações de transporte.  

Diante deste cenário o módulo Gestão de Transportes (SIGATMS) uniu toda expertise em gestão de transportes com a solução logística de roteirização de carga fornecida pela empresa MapLink, agregando inteligência e otimizando o processo de entregas e coletas dentro do SIGATMS. Fazendo com que as coletas/entregas tenham uma melhor disposição e ordem, e dessa maneira além de reduzir o tempo de operação também se reduz custos dentro da operação de transporte, além da obtenção prévia dos valores de pedágio.

O módulo passa a utilizar as APIs fornecidas pela MapLink para solucionar os problemas de ordem de entrega/coleta, melhor trajeto a ser realizado considerando o menor tempo ou menor distância, valores das praças de pedágio, plotagem e visualização do trajeto, coordenadas geográficas dos clientes.

  • API Planning tem como objetivo otimizar a operação de coleta/entrega, atribuindo a melhor ordem para as operações a fim de que o custo total seja reduzido e a produtividade aumente. 

  • API Trip é o serviço de roteirização para rotas simples e com múltiplos pontos, que se adapta ao tipo e especificações do veículo e leva em conta as especifidades e restrições do tempo da operação.

  • API Tolls  inclui os gastos com pedágio nos cálculos da operação e garante as previsões e controle de custos efetivos.

  • API GeoCode tem como objetivo encontrar as coordenadas geográficas dos endereços.


02. SISTEMAS ENVOLVIDOS

  • SIGATMS - As funcionalidades e rotinas que estão envolvidas no processão são: Cadastro de Clientes, Cadastro de Solicitante, Cadastro de Sequência de Endereço, Cadastro de Referências Geográficas, Viagem, Cadastro Roteirizador, Limpeza de Histórico de Integração.

  • MAPLINK - As APIs envolvidas são: GeoCode, Planning, Trip, Tolls e Map Display. Para obter mais informações, acesse: https://maplink.global/apis-maplink/ 


03. INTEGRAÇÃO

A integração tem como objetivo otimizar o processo de entrega e/ou coleta dos transportadores que utilizam o módulo SIGATMS.

Para que toda a solução funcione perfeitamente é necessário obter as coordenadas geográficas de todos os clientes, de acordo com os respectivos endereços. Para isso utilizamos a api GeoCode que retorna a latitude e longitude de acordo com o endereço enviado. As informações recebidas são gravadas no Cadastro de Referências Geográficas.

Os documentos serão ordenados na viagem, de acordo com a melhor sequência de entrega/coleta sugerida pela a api Planning.

Após obtido a melhor sequência de entrega/coleta a api Trip sugere a melhor rota para o veículo realizar, de acordo com a melhor sequência de entrega/coleta.

De acordo com a rota sugerida, obtém-se os gastos com pedágio de acordo com a quantidade de eixos dos veículos, através da api Tolls, e os valores de pedágio são atualizados automaticamente dentro da viagem.

Toda a visualização dos pontos de entrega/coleta, rota e praças de pedágio serão exibidas dentro do SIGATMS em um mapa, através da funcionalidade Map Display.


04. ESCOPO

A comunicação com as APIS e plataforma Maplink ocorreram a partir das rotinas: Cadastro de Clientes, Sequência de Endereço, Cadastro de Solicitantes e Wizard para envio das filiais (Cadastro de referências geográficas) para a api GeoCode; e também a partir das Viagens em Aberto para as apis Planning, Trip, Tolls e MapDisplay (Plotagem de mapas). 

As informações enviadas serão detalhadas abaixo.

Foram criadas novas funcionalidades no SIGATMS para complementar e auxiliar na integração como um todo:

  • Cadastro Roteirizador:  Foi criado o cadastro para armazenar as informações referente a integração como client_id, client_secret, app_id, app_code, URL Callback, URL Mapa e etc.. Muitos desses dados serão fornecidos pela MapLink. É possível também definir o tipo de retorno que a Maplink irá fornecer, pode-se optar pelo retorno por callback (webservice rest), em que o SIGATMS irá aguardar as respostas automaticamente. Ou pode-se realizar a integração via Ações Relacionadas no menu da viagem.
  • Consulta Histórico de Integração: As informações trafegadas pelas apis: planning, trip e tolls serão armazenadas na tabela DLU - Histórico de Integração.
  • Limpeza do Histórico de Integração: Criado a funcionalidade para eliminar fisicamente as informações referente ao histórico de integração.
  • Bloqueio de Viagem: Criado o bloqueio RT - Roteirizador, para ser acionado durante o fechamento da viagem, caso as respostas das apis ainda não tenham sido recebidas. 
  • Gravação da viagem: Ao utilizar a integração com o tipo de retorno = Callback, as informações para a planning, serão enviadas automaticamente ao final da gravação da viagem.
  • Webservice REST WSTMSMapLink: Criado webservice REST para subir o serviço que ficará aguardando o callback da Maplink.
  • Cadastro de Referências Geográficas: Criado o Wizard de Filiais para que a api Geocode seja acionada a partir dos endereços das filiais do sistema.
  • Plotagem do mapa: Plota o mapa tmsshowrota.html após o processamento completo das apis: planning, trip e tolls.
  • Viagem em Aberto: O envio de informações pode ser apenas realizado para viagens cujo status esteja em aberto.

IMPORTANTE!

  • Não é escopo desse documento descrever a instalação do ERP Protheus, nem suas configurações básicas. 
  • Para utilização da integração, o módulo SIGATMS  na versão 12.1.23 (ou superior) do Protheus deve estar com o ambiente atualizado com a última versão de RPO e o dicionário disponível na Central de Downloads TOTVS.
  • Para obter mais informações sobre como atualizar o dicionário de dados do Protheus 12, clique aqui.
  • A inteligência para fornecimento das melhores rotas e/ou sequência de entrega/coleta é responsabilidade da MapLink.
  • Deve-se preencher corretamente as informações país, estado, cidade, bairro, endereço e cep. O preenchimento incorreto dos campos ocasionará em coordenadas geográficas erradas e/ou inexistentes.
    • Deve-se preencher corretamente as informações citadas acima para:
      • Cadastro de filiais;
      • Cadastro de clientes;
      • Sequência de endereço;
      • Cadastro de solicitantes;
  • Deve-se preencher corretamente as informações capacidade máxima, volume máximo, altura externa, comprimento externo e largura externa do cadastro de veículos. O preenchimento incorreto dos campos ocasionará falhas de integração e/ou inconsistência no cálculo das APIs.


05. PRÉ-REQUISITOS PARA INSTALAÇÃO/IMPLANTAÇÃO/UTILIZAÇÃO

Premissas para o correto funcionamento:

  • Protheus versão 12.1.23 ou superior. 
  • Build superior à 131217A.
  • Dicionário de dados atualizado com tabelas referente a integração.
  • Repositório de dados atualizado com programas referente a integração;
  • Servidor de WebService deve estar corretamente configurado.
  • Servidor REST deve estar corretamente configurado.
  • Módulo SIGATMS deve estar corretamente configurado.
  • Possuir licenças Maplink.
  • Parâmetro de integração MV_ROTAINT habilitado.
  • Arquivos HTML
    • Os arquivos html (tmsshowrota.html, pedagio.png, iconBlue.png, iConRed.png, iconGray.png, iConYellow.png, tmsimg32.png e totvstec.js) devem estar na pasta definida na seção HTTP, tag PATH do appserver.ini.
  • Menu SIGATMS.xnu atualizado.


06. INSTALAÇÃO/ATUALIZAÇÃO

Este tópico tem por objetivo orientar a instalação da integração, visando o seu funcionamento completo. Instalação de produtos ou ferramentas necessárias podem referenciar outros documentos existentes, desde que estejam disponíveis no repositório de documentação da TOTVS ou sejam enviados junto com o documento da integração em si.

As informações mínimas necessárias para teste do tópico são:


07. PROTHEUS

No módulo SIGATMS acesse o menu Cadastro > Roteirizador > Config. Integração (TMSAO52)  para acessar o Cadastro de Roteirizador.

  • Clique em Incluir;
  • No campo ID Cliente informe o client_id fornecido pela Maplink;
  • No campo Cliente Secret informe o client_secret fornecido pela Maplink; 
  • No campo Tempo Token preencha com o tempo que o token irá expirar;
    • Pode-se preencher com 00:59; 
  • No campo URL CallBack informe a URL do servidor REST com o endpoint WSTMSMaplink;
    • Exemplo: http://localhost:8091/rest/api/tms/v1/wstmsmaplink;
  • No campo URL Mapa informe a URL do webservice aonde encontra-se o arquivo tmsshowrota.html;
    • Exemplo: http://localhost:8020/ws/tmsshowrota.html; 
  • No campo App Code (DLV_APPCOD) informe : totvs;
  • No campo Tipo de Retorno informe:
    • 2=Aguardar retorno roteirizador para o acesso e envio de informações Maplink ser realizado apenas via menu;
  • No campo Chave JS informe a Chave JavaScript informada pela Maplink.

No módulo SIGATMS acesse o menu Diversos > Limpeza Histórico Roteirizador (TMSAO53) para acessar a rotina Limpeza de Histórico.

  • Clique em Perguntas para filtrar a limpeza do histórico (DLU) de acordo com o número da viagem;
  • Clique em Informações e Executar para excluir fisicamente os registros;


08. FLUXO DAS INFORMAÇÕES

 

09. CADASTROS

GEOCODE

As rotinas Cadastro de Cliente, Sequência de Endereço e Cadastro de Solicitantes foram atualizadas para que ao final da gravação as informações referentes ao endereço sejam enviadas automaticamente para a api GeoCode a fim de obter as coordenadas geográficas do respectivo endereço. As coordenadas geográficas recebidas são gravadas na tabela DAR - Referência Geográficas, e é possível visualiza-las através da rotina Cadastro de Referências Geográficas - TMSAO15.Envio:

  • País;

  • Estado;

  • Cidade;

  • Bairro;

  • Rua;

  • Número;

  • CEP;

As informações recebidas são:

  • Latitude;
  • Longitude;


10. INTEGRAÇÃO

PLANNING

O objetivo da integração com a API Planning é otimizar os pontos de entrega/coleta e reordenar os documentos da viagem. 

A rotina de viagem foi alterada para que quando o campo Tipo de Retorno (DLV_TIPRET) da tabela Dados Cadastrais Roteirizador (DLV) esteja igual a 1=CallBack; a informações sejam enviadas automaticamente para a api Planning.

Pode-se também acionar a rotina a partir do menu criado na rotina Viagem (TMSA144): Ações Relacionadas > Roteirizador > Integra. 

Envio:

  • callback
    • Endpoint em que se encontra o serviço Rest - O endpoint deverá ser incluído no Cadastro Roteirizador (TMSAO52), campo URL CallBack (DLV_URLCAL);
  • logisticconstraints
    • Duração em tempo das operações de transporte (DTW);
      • DC6_DURAC é o campo que contém a duração das operações de transporte;
      • As operações enviadas são: 
        • Chegada de Viagem - MV_ATIVCHG;
        • Saída de Viagem - MV_ATIVSAI;
        • Chegada em Cliente - MV_ATVCHGC;
        • Saída do Cliente - MV_ATVSAIC;
        • Descarregamento - MV_ATIVDCA;
  • depots
    • Coordenadas geográficas do endereço da filial (SM0);
  • legislationprofiles
    • "DEFAULT";
  • operations
    • Informações dos documentos de entrega/coleta;
      • Número do documento;
      • Destinatário;
      • Prioridade;
      • Produto;
      • Tipo : DELIVERY ou COLLECTION;
      • Local de origem: Filial;
      • Peso;
      • Volume;
  • products
    • Produtos enviados nas notas fiscais;
  • sites
    • Coordenadas geográficas do endereços dos destinatários (Cliente, Solicitante ou Sequência de endereço);
  • vehicletypes
    • Volume máximo do veículo da viagem - DA3_VOLMAX;
    • Capacidade máxima do veículo da viagem - DA3_CAPACM;
    • Tamanho do veículo - DA3_COMEXT;
  • vehicles
    • Legislação vigente: "DEFAULT";
    • Janela de disponibilidade
      • Data atual;
      • Hora atual;
      • 1 dia após a data atual;
      • "23:59";
    • Local de origem: Filial;
    • Local de chegada: Filial;
    • Máximo de rotas: 1;
  • optmizationprofile: "BRAZIL37";
  • tripsprofile: "BRAZIL";

TRIP

O objetivo da integração com a api Trip é roteirizar os pontos de entrega/coleta e sugerir a melhor rota.

Envio:

  • points
    • Coordenadas geográficas dos destinatários;
  • profilename: "BRAZIL";
  • calculationmode - De acordo com a opção Modo de Cálculo (mv_par02) informado nas propriedades do roteirizador (Pergunte TMSAO46): Acesse a rotina Cadastro Roteirizador (TMSAO52) > Outras Ações > Propriedades Roteirizador;
    • 1=THE_FASTEST - Indica que a rota deverá ser calculada considerando o caminho mais rápido; 
    • 2=THE_SHORTEST - Indica que a rota deverá ser calculada considerando o caminho mais curto;
  • callback
    • Endpoint em que se encontra o serviço Rest - O endpoint deverá ser incluído no Cadastro Roteirizador (TMSAO52), campo URL CallBack (DLV_URLCAL);
  • startdate: Data e Horário atual;
  • useRealSpeeds - De acordo com a opção User velocidade real? (mv_par03) informado nas propriedades do roteirizador (Pergunte TMSAO46): Acesse a rotina Cadastro Roteirizador (TMSAO52) > Outras Ações > Propriedades Roteirizador;
    • 1 = true - Indica que deverá considerar o histórico de velocidade para o mesmo dia da semana e horário;
    • 2 = false - Indica que deverá considerar a velocidade da via;
  • vehiclespecification - Informações dos veículos
    • Altura máxima: DA3_ALTEXT;
    • Comprimento máximo: DA3_COMEXT;
    • Máxima distância entre eixos: DA3_COMEXT;
    • Capacidade máxima: DA3_CAPACM;
    • Capacidade máxima para materiais perigosos: DA3_CAPACM;
    • Capacidade máxima para materiais explosivos: DA3_CAPACM;
    • Capacidade máxima para materiais poluentes: DA3_CAPACM;
    • Capacidade máxima por eixo: DA3_CAPACM / DTR_QTDEIX;
    • Largura máxima: DA3_LAREXT;

TOLLS

A API Tolls fornece os valores e as praças de pedágio que existem no percurso da rota. Após obter os valores de pedágio dentro do complemento da viagem (DTR_VALPDG).

Envio:

  • legs
    • Rota e percurso calculado pela api TRIP;
    • Eixos - De acordo com a opção Calcula retorno filial? (mv_par01) informado nas propriedades do roteirizador (Pergunte TMSAO46): Acesse a rotina Cadastro Roteirizador (TMSAO52) > Outras Ações > Propriedades Roteirizador : 
      • 1=Sim - É enviada a quantidade de eixos (DTR_QTDEIX) e após a última entrega/coleta é adicionado um novo trecho retornando a filial e nesse último trecho é utilizado a quantidade de eixos do campo (DTR_QTDEIXV);
      • 2=Não - É enviada a quantidade de eixos (DTR_QTDEIX);
  • source: DEFAULT;

MAPDISPLAY

Essa funcionalidade permite a exibição do mapa e os pontos de coleta/entrega. O mapa será exibido quando todas as etapas da integração citadas acima forem concluídas com sucesso.

O mapa pode ser consultado a partir da rotina Viagem > Outras Ações > Roteirizador > Consulta (TMSAO50) após entrar na rotina Controle Integração TMS X Roteirizador acesse a opção Outras Ações > Vis. Mapa. 


11. LIMITAÇÕES/RESTRIÇÕES GERAIS

A integração ocorrerá somente quando o parâmetro MV_ROTAINT estiver habilitado.

Além disso, é necessário que esteja cadastrado e configurado corretamente:

GEOCODE

  • Cadastro de Cliente envia requisição para API Geocode.
  • Sequência de Endereço envia requisição para API Geocode.
  • Cadastro de Solicitantes envia requisição para APIGeocode.
  • Wizard de filiais envia requisição para API Geocode.

A API deverá retornar as coordenadas geográficas, retornando corretamente as informações apenas se os cadastros estiverem com os campos: país, estado, cidade, bairro, rua, número e CEP preenchidos corretamente.

PLANNING

O envio de informações e tratamento das informações poderá ser realizado de duas maneiras:

  • Automaticamente ao gravar a viagem. (DLV_TIPRET = 1-CallBack);
    • O servidor REST deverá estar cadastrado corretamente;
    • O campo DLV_URLCAL deverá estar preenchido com o Endpoint do serviço WSTMSMapLink;
    • As informações planning serão enviadas automaticamente;
    • O sistema irá processar e enviar as mensagens Trip e Tolls automaticamente após o retorno do processamento da MapLink;
  • Manualmente, ao acessar na rotina de viagem a opção Outras Ações > Roteirizador > Integra; 

TRIP

O envio de informações e tratamento das informações poderá ser realizado de duas maneiras:

  • Automaticamente ao gravar a viagem. (DLV_TIPRET = 1-CallBack);
    • O servidor REST deverá estar cadastrado corretamente;
    • O campo DLV_URLCAL deverá estar preenchido com o Endpoint do serviço WSTMSMapLink;
    • As informações trip serão enviadas automaticamente;
    • O sistema irá processar e enviar a mensagem Tolls automaticamente após o retorno do processamento da MapLink;
  • Manualmente, ao acessar na rotina de viagem a opção Outras Ações > Roteirizador > Integra; 

TOLLS

O envio de informações e tratamento das informações poderá ser realizado de duas maneiras:

  • Automaticamente ao gravar a viagem. (DLV_TIPRET = 1-CallBack);
    • O servidor REST deverá estar cadastrado corretamente;
    • O campo DLV_URLCAL deverá estar preenchido com o Endpoint do serviço WSTMSMapLink;
    • As informações tolls serão enviadas automaticamente;
  • Manualmente, ao acessar na rotina de viagem a opção Outras Ações > Roteirizador > Integra; 


12. COMO FAZER

INTEGRAÇÃO

  • No SIGATMS habilite o parâmetro de integração MV_ROTAINT.

  • Acesse a rotina Dados Cadastrais Roteirizador e cadastre as informações de acordo com as configurações e assinatura Maplink.

  • Atualize o cadastro de: Clientes, Sequência de Endereço e Solicitantes. 

  • Na rotina Cadastro de Referências Geográficas, clique em Outras Ações > Wizard Filiais.

  • Selecione as filiais que deseja obter as coordenadas geográficas, e prossiga a operação.

  • Na rotina Viagem, clique em Outras Ações > Roteirizador > Integra.

  • Aguarde o envio das informações e a respectiva plotagem do mapa.


13. CHECKLIST DE SUPORTE DE APLICAÇÃO

CHECKLIST DE VERIFICAÇÕES

  • Relacione os itens de verificações para que o Atendente possa:

    • Identificar a build utilizada;

    • Identificar se a conexão com a internet está estável;

    • Identificar se servidor webservice está com funcionamento correto;

    • Identificar se servidor Rest está com o funcionamento correto;

    • Identificar se o cliente destinatário (Cliente, Sequência de Endereço ou Solicitante) está com o endereço cadastrado corretamente;

    • Verificar se foi obtido as referências geográficas para o cliente destinatário;

    • Verificar se foi obtido as referências geográficas para a filial;

    • Verificar se os campos do cadastro de veículos estão preenchidos corretamente: DA3_CAPACM, DA3_VOLMAX, DA3_COMEXT, DA3_LAREXT,DA3_ALTEXT;