Histórico da Página
CONTEÚDO
Índice | ||||||||
---|---|---|---|---|---|---|---|---|
|
01. 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 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 citadas acima para:
- 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_MAPLINKROTAINT 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 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:
- Execute a rotina UPDDISTR - Atualizador de dicionário e base de dados - UPDDISTR.
- Configure o servidor REST - 01. Configuração.
- Configure o 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.
- Habilite o parâmetro mv_maplinkrotaint.
- Atualize o menu sigatms.xnu.
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 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;
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;
- Duração em tempo das operações de transporte (DTW);
- 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;
- Informações dos documentos de entrega/coleta;
- 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_MAPLINKROTAINT 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_MAPLINKROTAINT.
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;