INTEGRAÇÃO ROTEIRIZADOR MAPLINK X SIGATMS

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 API's 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.

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 maiores informações acesse: https://maplink.global/apis-maplink/ 

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.

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.

Pré-requisitos 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_MAPLINK habilitado.
• Arquivos HTML
  • Os arquivos html (tmsshowrota.html, pedagio.png, tmsimg32.png e totvstec.js) devem estar na pasta definida na seção HTTP, tag PATH do appserver.ini.
• Menu SIGATMS.xnu atualiado.

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 tópico são:

• Executar programa UPDDISTR - Atualizador de dicionário e base de dados - UPDDISTR;
• Configurar servidor REST - 01. Configuração;
• Configurar serviço de WebService - Configurar Portais e Webservices;
• Os arquivos tmsshowrota.html, pedagio.png, tmsimg32.png e totvstec.js devem estar na pasta definida na seçao http, tag path do appserver.ini;
• Habilitar parâmetro mv_maplink;
• Atualizar o menu sigatms.xnu;

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 o 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 ID GeoCode informe o app_id fornecido pela Maplink para consumo da api GeoCode; 
• No campo App Code GeoCode informe o app_code fornecido pela Maplink para consumo da api GeoCode;
• No campo Tipo de Retorno informe:
  • 1=Callback para o retorno da solução MapLink ocorrer através do servidor Rest e o envio ser realizado ao final da gravação da viagem de maneira automática;
  • 2=Aguardar retorno roteirizador para o acesso e envio de informações Maplink ser realizado apenas via menu;

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;

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

Suporte

O suporte aos recursos da Integração será de responsabilidade de todas as linhas, sendo assim as equipes de suporte dos produtos RM Conector e Backoffice Protheus estarão aptas a fazer a primeira análise e, quando necessário, repassar para a equipe mais adequada em cada caso.

Observação: Este modelo de suporte está sendo revisado pela TOTVS.

Fluxo das Informações

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;

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. 

Cadastros

Descreva características gerais do fluxo de informações e que serão comuns para este tipo de entidade. Características particulares para cada entidade deverão ser citadas em tópicos específicos de cada entidade.

Sempre que existir (a sugestão é sempre criar) e for agregador ao documento acrescentar aqui os diagramas/imagens ou até mesmo colocar tais diagramas diretamente na especificação dos processos

Em seguida faça uma descrição para cada um dos fluxos para cada entidade

<Transação/Entidade>

Identificador da Mensagem: <mensagem>

Versão: <versão>

Módulo <marca 1>: <BackOffice – Gestão xxxxxxx>

Módulo <marca 2>: <SIGAXXX>

Tipo de Envio: <Assíncrona/Síncrona>

Notas:

Observações sobre comportamento desta mensagem ou dos processos envolvidos nela/para ela

A seguir descrever as variações, particularidades da mensagem e processos (integração) de acordo com cada marca

Limitações/Restrições

Descreva limitações e restrições para a integração que está sendo descrita.

Processos

Descreva características gerais do fluxo de informações e que serão comuns para este tipo de entidade. Características particulares para cada entidade deverão ser citadas em tópicos específicos de cada entidade.

Sempre que existir (a sugestão é sempre criar) e for agregador ao documento acrescentar aqui os diagramas/imagens ou até mesmo colocar tais diagramas diretamente na especificação dos processos

Em seguida faça uma descrição para cada um dos fluxos para cada entidade

<Transação/Processo>

Tipo de Fluxo: Protheus -> RM

Mensagem: Request_1_000

Versão: 1.000

Descrição de todo o comportamento e funcionamento do processo. Breve contexto, origem, regras, integração (geração da mensagem, envio, recebimento no destino), o quê supostamente irá ocorrer no destino, retorno, impacto, consequências, o que foi afetado, como conferir, validar, etc o retorno.

Acrescentar um diagrama do processo.

A seguir descrever as variações, particularidades da mensagem e processos (desta integração) de acordo com cada marca

Notas:

Observações sobre comportamento desta mensagem ou dos processos envolvidos nela/para ela

Limitações/Restrições

Descreva limitações e restrições para a integração que está sendo descrita. 

Limitações / Restrições Gerais

Descreva limitações e restrições para cada fluxo descrito no tópico anterior. Exemplo:

Integração só ocorrerá caso o parâmetro MV_MAPLINK esteja habilitado e 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 api Geocode.
• Wizard de filiais envia requisição para api Geocode.

A api deverá retornar as coordenadas geográficas, e só retornará corretamente as informações 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; 

Como fazer

Integração:

• No SIGATMS habilite o parâmetro de integração MV_MAPLINK.
• 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, acesse Outras Ações > Wizard Filiais. Escolha as filiais que deseja obter as coordenadas geográficas, e prossiga a operação.
• Na rotina Viagem, acesse o botão Outras Ações > Roteirizador > Integra, e aguarde o envio das informações e a respectiva plotagem do mapa.

Checklist de suporte da aplicação

Checklist de Verificações:

Relacione 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;

Anexos