Histórico da Página
Conteúdo
Âncora | ||||
---|---|---|---|---|
|
Índice | ||||||||
---|---|---|---|---|---|---|---|---|
|
1. Contexto de Negócio
O TOTVS OMS passa a ter uma nova funcionalidade para realizar a montagem das cargas, o sequenciamento das entregas e a visualização do mapa das entregas.
Com base na seleção de um grupo de Pedidos ou itens de Pedidos de Vendas liberados, veículos e mais algumas configurações serão geradas cargas automaticamente de forma a otimizar a ocupação dos veículos e traçar a melhor rota de entrega dos Pedidos.
Para utilizar essa funcionalidade, basta aderir ao plano Complemento do termo de uso da TOTVS Store que mais se adequa ao seu cenário e seguir as orientações descritas na sequência deste documento.
Informações | ||
---|---|---|
| ||
Informações adicionais sobre como será realizada a montagem da carga/sequenciamento da entrega podem ser obtidas no documento: TOTVS Planejamento de Rotas. |
2. Instalação / Configuração
Informações | |||||
---|---|---|---|---|---|
| |||||
Caso aplique os pacotes de expedição contínua do OMS, os patches abaixo não são necessários.
|
Após a atualização dos pacotes da expedição contínua, se desejar conferir se a aplicação dos pacotes está correta, na tabela abaixo são listados os fontes e suas versões mínimas:
Módulo | Rotina | Descrição | Versão Mínima |
---|---|---|---|
Faturamento | FATXFUN.PRX | Funções genéricas FAT. | 05/11/2021 19:21:13 |
Faturamento | MATA410.PRX | Pedidos. | 05/11/2021 19:21:13 |
Faturamento | MATA461.PRX | Preparação dos documentos de saída. | 05/11/2021 19:21:13 |
Faturamento | MATV410.PRW | Funções para o estorno de pedidos. | 05/11/2021 19:21:13 |
OMS | OMSA200.PRW | Montagem de carga. | 24/05/2022 13:42:41 |
OMS | OMSATPR1.PRW | Envio de pedidos - TPR (Menu). | 29/09/2022 20:38:01 |
OMS | OMSATPR1A.PRW | Funções do envio de pedidos - TPR. | 29/09/2022 18:08:50 |
OMS | OMSATPR2.PRW | Processamento do callback do retorno das viagens/carga - TPR. | 13/10/2022 14:09:04 |
OMS | OMSATPR3.PRW | Visualização do mapa da carga gerada (OMSA200 > Ações Relacionadas > Visualizar Mapa). | 28/09/2022 13:28:03 |
OMS | OMSATPR4.PRW | Validações para a alteração e estorno de pedidos integrados com o TPR. | 18/08/2022 17:27:45 |
OMS | OMSATPR5.PRW | Envio de roteirização TPR via OMSA200. | 29/09/2022 20:38:01 |
OMS | OMSATPR6.PRW | Recebimento do callback de roteirização via OMSA200. | 13/10/2022 14:09:04 |
OMS | OMSATPR7.PRW | Atualização de rota e carga via callback. | 15/06/2022 19:09:30 |
OMS | OMSXFUN.PRW | Funções genéricas OMS. | 16/11/2021 16:38:22 |
TMS | TMSAC18.PRW | Métodos de envio - Integração planejamento de rotas. | 22/08/2022 15:47:53 |
TMS | TMSAC19.PRW | Painel Integração Planejamento de Rotas (TPR): | 21/10/2021 15:44:14 |
TMS | TMSAC20.PRW | Configuração Planejamento de Rotas: | 29/06/2022 14:52:09 |
TMS | TMSAC23.PRW | Controle de Integração Planejamento de Rotas: | 03/01/2022 15:11:55 |
TMS | TMSAC24.PRW | Montagem e visualização do mapa. | 14/01/2022 17:47:30 |
TMS | TMSAC25.PRW | Montagem e visualização do mapa. | 05/07/2022 14:37:14 |
TMS | TMSAO15.PRW | Cadastro de referência geográfica. | 26/09/2022 11:21:57 |
TMS | TMSAO48.PRW | Integração rota inteligente. | 03/03/2022 11:02:53 |
TMS | TMSO46API.PRW | Métodos callback Planejamento de Rotas. | 26/09/2022 11:20:02 |
TMS | index.html | Arquivo para exibição do mapa na pasta Web. | 23/05/2022 17:30:42 |
TMS | tprchannel.js | Arquivo para exibição do mapa na pasta Web. | 18/10/2021 08:22:31 |
2.1. Arquivos Relacionados ao Mapa (Data / Web)
Baixe aqui os arquivos index.html e tprchannel.js e salve na pasta Web do seu ambiente Protheus.
Exemplo: C:\Bases\environment\data\web. Estes arquivos serão mencionados novamente na configuração do Appserver.ini (2.4).
2.2. Atualização do Help
Para atualizar o Help de campos é necessário inserir (somente) o arquivo da expedição contínua hlppor.txt na pasta systemload e seguir os passos de acordo com o documento: Atualização de Help.
2.3. Atualização do Menu do OMS
Atualize o menu do Protheus OMS baixando somente o arquivo sigaoms.xnu, de acordo com o seu ambiente:
Atualização de menu com dicionário no banco: Atualização de menus que estão no Banco de Dados.
Atualização de menu sem dicionário no banco: Atualizar menus dos módulos.
A atualização em questão cadastrará as novas rotinas de menu:
Rotina | Menu |
---|---|
OMSATPR1 | Envio de Pedidos - TOTVS Planejamento de Rotas (TPR) |
TMSAO15 | Cadastro Referências Geográficas |
TMSAC19 | Painel Integração Planejamento de Rotas |
TMSAC23 | Controle de Integração Planejamento de Rotas |
TMSAC20 | Configuração Planejamento de Rotas |
2.4. Configurações no Appserver.ini
Para realizar as integrações com o TPR é necessário possuir a configuração REST no ambiente, sendo possível reutilizar um Appserver ou gerar outro para receber as integrações REST.
Também é necessário realizar 3 blocos de configurações no Appserver.ini, conforme exemplos a seguir.
2.4.1. Configuração do REST do Protheus
Link para o documento: 1. Configuração do REST do Protheus.
Bloco de código | ||||
---|---|---|---|---|
| ||||
;************************************ ;*** REST ;************************************ [HTTPV11] Enable=1 Sockets=HTTPREST MAXSTRINGSIZE=500 [HTTPREST] Port=8084 URIs=URIHTML SECURITY=0 [URIHTML] URL=/rest PrepareIn=All Instances=1,2 CORSEnable=1 AllowOrigin=* [HTTPJOB] MAIN=HTTP_START ENVIRONMENT=environment1 [ONSTART] JOBS=HTTPJOB RefreshRate=120 |
2.4.2. Configuração HTTP
As configurações HTTP servem para a exibição do mapa de roteirizações.
Bloco de código | ||||
---|---|---|---|---|
| ||||
[HTTP] ENABLE=1 PATH=C:\Bases\environment\data\web PORT=8021 INSTANCES=1,10 SESSIONTIMEOUT=60 INSTANCENAME=WS_HTTP [10.173.11.38:8021/ws] ENABLE=1 PATH=C:\Bases\environment\data\web ENVIRONMENT=environment1 INSTANCENAME=WS_OMSCARGA RESPONSEJOB=JOB_WS_OMS DEFAULTPAGE=wsindex.apw |
Informações | ||
---|---|---|
| ||
|
2.4.3. Configuração de Portais e Webservices
Link para o documento: Configurar Portais e Webservices.
Bloco de código | ||||
---|---|---|---|---|
| ||||
[JOB_WS_OMS] TYPE=WEBEX ENVIRONMENT=environment1 INSTANCES=1,10 INSTANCENAME=JOB_WS_OMS ONSTART=__WSSTART ONCONNECT=__WSCONNECT PREPAREIN=All SIGAWEB=WS |
2.5. Campos e Parâmetros Utilizados (SIGACFG)
2.5.1. Campos
Informações | ||
---|---|---|
| ||
Assinale, via SIGACFG, os seguintes campos como usados:
|
2.5.2. Parâmetros
Parâmetro | Descrição | Valor |
---|---|---|
MV_ROTAINT | Habilita rotas inteligentes. | .T. |
MV_TPRCLOG | Define a visualização do log de operações do TPR no ConsoleFile configurado. Informe .F. após a implantação. Inclua no ini do REST, na seção do Environment, a chave FWTRACELOG=1. | .F. |
MV_OMSLROT | Define se é possível alterar a rota gerada. | .F. |
MV_OMSUROT | Define a URL de callback da rota alterada. | URL não obrigatória. |
MV_OMSPROT | Na integração TPR, ao selecionar o funcionamento de entregas customizadas, define o funcionamento padrão para usuários sem regras de entrega. | Default 1. 1 = Sem restrição / 2 = Dias úteis / 3 = De manhã / 4 = À tarde Se vazio, informa uma inconsistência de integração, caso não haja Janelas de Entregas definidas e o parâmetro do funcionamento das entregas esteja definido como customizado. |
MV_HVERAO | Verifique se o local físico do servidor está em Horário de Verão. | |
MV_CDTPOP | Indica qual o código de operação será enviado ao TOTVS GFE, na geração da carga, sendo que o mesmo deve ser cadastrado previamente no TOTVS GFE e vinculado. Esse parâmetro alimentará o campo DAK_CDTPOP. | 5 |
MV_CDCLFR | Código da Classificação de Frete Padrão utilizado na importação de Documentos de Carga. Esse parâmetro alimentará o campo DAK_CDCLFR. | |
MV_OMSENTR | Define o número de incremento do campo Sequência de Entrega (DAK_SEQENT), na rotina OMSA200 (Montagem de Cargas). | Informar o conteúdo padrão igual a 5 (cinco). |
2.6. Configuração das URLs de Integração TPR
2.6.1. Configuração de E-mail do Usuário Para Utilização do TPR
Acesse o SIGACFG > Usuário > Senhas > Usuários e selecione um usuário para receber o token de ativação TPR.
Este token será enviado após a configuração do TPR na rotinaTMSAC20 (Config. Planejamento de Rotas).
2.6.2. Acesse Atualizações > Planejamento de Rotas > Config. Planejamento de Rotas (TMSAC20)
- Realize as parametrizações conforme descrito a seguir:
Campo | Descrição | |||||
---|---|---|---|---|---|---|
ID Cliente | Campo livre para identificação. | |||||
URL Callback (REST) | Essa URL é enviada do Protheus para a API TPR, ao solicitar a roteirização TPR. Nesta solicitação, a API TPR realizará a rejeição ou confirmação dos Pedidos para planejamento. Se for confirmado o recebimento, após alguns minutos, a API TPR consumirá a URL Callback (URL REST) do servidor Protheus, para enviar os dados referentes ao cálculo de roteirização. Informe o IP e Porta externa do servidor REST do Protheus (IP:PORTA + /REST/V1/WSTPRNEOLOG/) para utilização no recebimento dos retornos do TOTVS Planejamento de Rotas (TPR) referente a Roteirização.
| |||||
Bloqueado | Informe 2 - Não. | |||||
Token | Campo não editável. Será preenchido automaticamente no teste de conexão a seguir. | |||||
Data Token | Campo não editável. Será preenchido automaticamente no teste de conexão a seguir. | |||||
Hora Token | Campo não editável. Será preenchido automaticamente no teste de conexão a seguir. | |||||
Tipo Retorno | Informe 1- Callback. | |||||
URL Mapa HTML | Informe o IP e Porta do servidor Webservice do Protheus (IP:PORTA + /ws/index.html), para utilização no serviço de Mapa do TOTVS Planejamento de Rotas (TPR). | |||||
IP e Porta | Informados no AppServer, em Configurações HTTP. Essa informação é importante para apresentar o mapa. O IP e a Porta cadastrados nessa seção precisam ser visualizados em toda a rede de acesso Smartclient do ambiente. Caso exista algum bloqueio de rede interna, o mapa não será apresentado no Protheus. | |||||
Roteirizador | Informe 2 - TPR Neolog. | |||||
URL Token | URL disponibilizada pelo TPR para controle do Token do TOTVS Planejamento de Rotas (TPR). | |||||
URL Roteirização | URL disponibilizada pelo TPR para controle dos serviços de Roteirização do TOTVS Planejamento de Rotas (TPR). Utilize HTTPS://PLANEJAMENTOROTAS.TOTVS.COM/V1/TPR-ROUTING | |||||
URL Geocode | URL disponibilizada pelo TPR para controle dos serviços de Geolocalização do TOTVS Planejamento de Rotas (TPR). Utilize HTTPS://PLANEJAMENTOROTAS.TOTVS.COM/V1/TPR-GEOLOCATION-SYNC | |||||
URL Geo Assi | URL disponibilizada pelo TPR para controle dos serviços de Geolocalização Assíncrona doTOTVS Planejamento de Rotas (TPR). | |||||
Token / Data Token / Hora Token | Estese campos serão preenchidos automaticamente pelo retorno do TOTVS Planejamento de Rotas (TPR). |
- Após ser realizada a inclusão do registro, clique em Outras Ações > Testar Conexão para obter os dados do token do TPR.
- Esta ação enviará um e-mail e será necessário clicar em Ativar Token:
Informações | ||
---|---|---|
| ||
|
3. Processo de Utilização
3.1. Premissas
É necessário preencher o endereço completo dos clientes (endereço com número, CEP, bairro, cidade, estado e país) ou gerar as geolocalizações para as entidades na rotina TMSA015 (Referência Geográfica).
Quanto melhor for a qualidade das informações do endereço, maior a probabilidade de identificar corretamente as coordenadas atreladas ao mesmo.
Também será possível verificar no mapa as coordenadas geolocalizadas e, caso as mesmas não representem o ponto exato, pode ser ajustado manualmente o marcador para a posição exata.
Os veículos devem estar cadastrados na rotina OMSA060 (Cadastro de Veículos).
Os pedidos de vendas (MATA410 - Pedidos de Venda) devem ter sido gerados e liberados (MATA440 - Liberação de Pedidos de Venda).
3.2. Como Enviar Pedidos Para a Roteirização
Execute a rotina OMSATPR1 (Envio de Pedidos) - TOTVS Planejamento de Rotas (TPR).
Na tela Filtro para os Pedidos, informe os filtros para a exibição dos Pedidos de Venda e clique em OK.
Selecione os Pedidos que devem ser enviados para a roteirização.
Selecione os veículos que devem ser considerados no cálculo para utilização.
- Informe a quantidade de eixos para o cálculo do pedágio de cada veículo selecionado. Caso não sejam preenchidos os eixos, a quantidade será obtida por meio do Cadastro do Veículo.
Informe os parâmetros para a roteirização.
Clique em Enviar.
Neste momento, os Pedidos e a roteirização permanecerão na situação Pendente, até o retorno da roteirização.
- Caso necessário, clique em Integrações do Item para visualizar a situação do envio e todos os itens de Pedidos enviados para a roteirização.
3.3. Como Consultar o Status dos Pedidos Enviados e o Status da Integração
Acesse a rotina TMSAC19 (Painel Integração Planejamento de Rotas (TPR)).
A tabela superior apresenta a identificação da roteirização e seustatus. A tabela inferior apresenta os itens de pedidos enviados e a carga relacionada a cada item.
No exemplo abaixo, foi necessária a geração de uma carga somente.Ao clicar em Controle de Integração serão visualizados os JSONS da integração e as informações de data/hora de envio e data/hora de retorno do processamento.
3.4. Como Visualizar as Roteirizações
Acesse a rotina OMSA200 (Montagem de Carga).
Informe os parâmetros para a visualização das cargas;
Encontre a carga gerada pelo TPR (INTEGRADO COM TPR (MAPA DISPONÍVEL) e clique em Visualizar Mapa TPR.
3.5. Como Definir a Geolocalização Exata
Acesse a rotina TMSAO15 (Cadastro de Referências Geográficas).
Inclua ou altere a geolocalização de um usuário e clique em Confirmar.
3.6. Como Realizar a Roteirização Via OMSA200
- Acesse a rotina OMSA200 (Montagem de Carga), com a carga montada, e clique em Carregamento > Associar Veículo.
- Informe o veículo da carga.
- Informe a quantidade de eixos para o cálculo do pedágio do veículo selecionado, clicando em Outras Ações > Qtd. de Eixos Roteirização TPR. Caso não sejam preenchidos os eixos, a quantidade será obtida pelo cadastro do veículo.
- Informe os parâmetros para planejamento da rota em Outras Ações > Parâmetros Roteirização TPR.
- Clique em Outras Ações > Planejar Roteirização TPR.
- Aguarde alguns minutos.
- Se a filial e os usuários não estiverem geolocalizadas, o Sistema efetuará a busca das coordenadas no envio do planejamento para o TPR.
- Após aguardar alguns minutos, a roteirização será finalizada e apresentada com os pedágios e os pontos de paradas de cada cliente.
- Nesta roteirização foi considerado o retorno para a filial, totalizando 5 pontos de parada do caminhão:
3.7. Como Gerar um Ponto de Passagem na Roteirização
- Acesse a rotina OMSA200 (Montagem de Carga).
- Clique na carga roteirizada e, após, selecione a opção Outras Ações > Visualizar Mapa TPR.
- Clique em Novo ponto e selecione o intervalo de paradas.
- Clique duas vezes na área do mapa para adicionar o ponto de passagem e confirme.
- Aguarde alguns segundos e clique em Atualizar ou pressione a tecla F5, para atualizar os dados da roteirização.
3.8. Como Alterar um Ponto de Entrega na Roteirização
- Acesse a rotina OMSA200 (Montagem de Carga).
- Clique na carga roteirizada e, após, selecione a opção Outras Ações > Visualizar Mapa TPR.
- No mapa, clique em Alterar localidade.
- Mova o ponto do mapa cuja localidade exata deve ser alterada e confirme.
- Aguarde alguns segundos e clique em Atualizar ou pressione a tecla F5 para atualizar os dados da roteirização.
3.9. Como Alterar a Ordem das Entregas na Roteirização
- Acesse a rotina OMSA200 (Montagem de Carga).
- Clique na carga roteirizada e, após, selecione a opção Outras Ações > Visualizar Mapa TPR.
- No mapa, clique em Trocar ordem das paradas.
- Selecione as paradas cuja ordem deve ser alterada e confirme.
- Aguarde alguns segundos e clique em Atualizar ou pressione a tecla F5 para atualizar os dados da roteirização.
3.10. Como Funcionam as Restrições de Janelas de Entrega na Roteirização TPR
- Para ativar esta funcionalidade, selecione a opção Funcionamento entregas = Customizado, em Outras Ações > Parâmetros do planejamento.
- Esta opção deve ser selecionada na tela de Envio de Pedidos - TOTVS Planejamento de Rotas (TPR) ou na rotina OMSA200 (Montagem de Carga).
- Para a integração o cadastro das regras e exceções nas rotinas OMSA120 (Cadastro de Regras de Entregas) e OMSA350 (Calendário de Janelas de Entregas) é limitado. São consideradas as regras para os usuários e as exceções para os veículos.
Informações | ||
---|---|---|
| ||
|
3.10.1 Cadastro de Regras Para Cliente(s)
- Informe o grupo de usuáriosou o cliente/loja da regra.
- Selecione ou não um calendário.
- Se for selecionado um calendário, este deve ser do tipo Semanal, no qual são informados os dias da semana de trabalho.
- Se não for selecionado um calendário, serão considerados todos os dias da semana com os horários preenchidos.
- Informe somente o tipo Regra.
3.10.2 - Cadastro de Exceções Para Veículos
Por padrão, as regras de exceção dos veículos são validadas nas integrações TPR via Envio de Pedidos - TOTVS Planejamento de Rotas (TPR) (OMSATPR1) ou OMSA200 (Montagem de Carga).
Sendo assim, não é necessário selecionar a opção Funcionamento entregas = Customizado, para validar os veículos.
- Informe o grupo de usuários ou o usuário/loja da regra ou exceção para os veículos.
- Ao informar o veículo, este não será considerado na roteirização TPR para este usuário ou grupo de usuários.
- Ao informar o grupo de veículos, estes não serão considerados na roteirização TPR para este usuário ou grupo de usuários.
3.11. Como Cancelar Uma Roteirização Enviada
É possível desconsiderar o retorno da roteirização enviada, mas não cancelar a roteirização solicitada.
Ou seja, o ticket de integração será contabilizado, mas o retorno será desconsiderado no Protheus.
3.12. Como Restringir a Alternância de Entrega Entre Estados
3.13 - Como salvar os resultados da busca de geolocalizações:
Abrir o programa Controle de Integração Planejamento Rotas (TPR)
Criar filtro para encontrar o registro de integração desejado. Para o caso abaixo é Chave Entid. igual a " 00000501" (Filial da entidade + Código da entidade + Loja da Entidade).
Filtrar o registro desejado:
Clicar em visualizar. O conteúdo do campo Msg Envio (DLU_ENVIO) é o json de envio para obter as coordenadas geográficas. E o conteúdo do campo Retorno Post (DLU_RETENV) é a resposta da api para a solicitação realizada.
Mais informações sobre as rotinas podem ser consultadas na tabela abaixo:
Rotina | Implementação | |||||
---|---|---|---|---|---|---|
TMSAC20 - Configuração Planejamento de Rotas | Parametrize as URLs e gere o token. | |||||
MATA030 - Cadastro de Clientes | Verifique os endereços dos usuários e o país. | |||||
EICA100 - Países | Verifique a sigla BRA, para o país Brasil. | |||||
OMSA060 - Veículos | Informe o novo campo:
| |||||
TMSAO15 - Coordenadas Geográficas | Verifique as coordenadas geradas para os usuários e a localização no mapa. A rotina permite que sejam geradas as coordenadas para o usuário, mesmo que ele não possua endereço cadastrado.
| |||||
MATA010 - Produtos | Verifique os campos B1_PESO, B1_PESBRU, B5_ALTURLC, B5_LARGLC e B5_COMPRLC. | |||||
MATA410 - Pedidos | Gere os Pedidos para os usuários e libere os Pedidos.. | |||||
OMSATPR1 - Envio de Pedidos - TOTVS Planejamento de Rotas | Selecione os Pedidos, os veículos e informe os parâmetros (F6). Ao enviar os Pedidos, o browse de Pedidos será atualizado e os mesmos aparecerão com a situação Pendente. Será gerada uma roteirização na tabela DMR (Roteirização - TPR) e os itens serão identificados na tabela DMS (Itens Roteirização - TPR). Para visualizar esta integração, clique em Integrações do Item, na rotina OMSATPR1 (Envio de Pedidos), ou acesse diretamente a rotina TMSAC19 (Consulta Planejamento de Rotas). | |||||
TMSAC19 - Painel Integração Planejamento de Rotas (TPR) | Apresenta a situação da integração, bem como, o resultado de cada item, sendo que os itens são gravados separadamente por meio de cada SC9 do Pedido liberado. Ao realizar a seleção de um Pedido para integração, serão considerados apenas os itens liberados. Os itens poderão ser apresentados nas seguintes situações:
O TMSAC19 permite o cancelamento do envio para a alteração dos pedidos por meio do botão Cancelar Envio. A alteração do envio não será realizada no TPR. Este cancelamento apenas desconsidera qualquer resultado do planejamento. Nessa rotina é possível acionar o JSONS gerados na API de roteirização, por meio da aba Controle de Integração. Esta aba acessa a rotina TMSAC23 (Controle de Integração). | |||||
TMSAC23 - Controle de Integração | Apresenta o JSON de envio de Pedidos, no qual o TPR realiza uma validação prévia para processamento e retorna ao Protheus. Caso a validação retorne sucesso, o TPR mantém o processamento e retornará um Callback para o Protheus, após alguns minutos. Todas essas mensagens são registradas para análise, caso seja necessário. | |||||
OMSA200 - Montagem de Carga | No sucesso do planejamento TPR serão geradas as cargas, sendo que estas poderão ser visualizadas. O campo que apresenta a disponibilização do mapa é o DAK_STROTE, com a informação Integrado com TPR (Mapa disponível). Para visualizar o mapa, clique em Outras Ações > Visualizar Mapa TPR. A visualização do mapa apresenta a ordem de entrega, o tempo de serviço, quilometragem, peso, volume, duração, o retorno para a filial (caso parametrizado), viagem extra (uma viagem extra é quando o TPR informa que durante a análise faltaram veículos para todos os Pedidos. Para poder entregar os pedidos, o planejamento sugeriu reutilizar um dos veículos enviados).
| |||||
MATA410 - Pedidos | Ao realizar a alteração de um Pedido que foi enviado para roteirizar, o usuário receberá um alerta sobre o relacionamento. Neste caso, o usuário tem a opção de manter o Pedido sem alteração e manter a roteirização ou de continuar a alteração do Pedido e perder os dados de roteirização. | |||||
MATA461 - Preparação dos Documentos de Saída | Ao confirmar o estorno da liberação de um Pedido que possua roteirização, o usuário receberá um alerta que perdeu a roteirização relacionada ao item. |
4. Informações Técnicas Sobre as Integrações - Incluindo Exemplos das Mensagens Trafegadas
A integração é realizada em APIS REST.
Abaixo segue um resumo das integrações:
Geração do Token (gerado na instalação). Documentação API: Criação de token.
Geolocalização síncrona (realizada ao alterar clientes ou no envio de pedidos, quando o cliente não possui geolocalização). Documentação API: Integração de Geolocalização - Síncrona.
Roteirização. Essa API acontece em 3 etapas:
O Protheus envia os Pedidos,
Recebe uma resposta do recebimento do TPR.
Após o recebimento, o TPR retornará as viagens geradas em alguns minutos (3). Documentação API: Integração de Roteirização - ERPs
Segue o detalhamento das integrações:
4.1. Geolocalização
Retorna as coordenadas geográficas de acordo com o endereço do usuário cadastrado (MATA030).
Integração executada ao alterar o usuário via MATA030 (Cadastro de Clientes) ou via Envio de Pedidos - TPR (OMSATPR1), quando o usuário não possui coordenadas geradas (TMSAO15 - Tabela DAR).
- Exemplo de Envio
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "address":{ "identifier":" MG000101", "address":"AVENIDA CONTORNO, 6283 ", "state":"MG", "zipCode":"30110931", "country":"BRA", "city":"BELO HORIZONTE " }, "callbackAuthenticationType":"NONE", "dateCall":"2021-10-28T22:46:14", "callbackURL":"HTTP://179.223.161.99:8084/REST/V1/WSTPRNEOLOG/", "version":"7.00.191205P-20210601", "qualifiers":"{\"usuario\":\"Administrador\"}", "callbackAuthenticationValue":"", "system":"OMS" } |
- Exemplo de Retorno
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "dateCall":"2021-10-29T01:46:32.413Z", "version":"", "geolocationResult":{ "identifier":" MG000101", "success":true, "latitude":-19.9405175, "longitude":-43.9359666, "messages":[ { "messageCode":"TPRGS0000", "message":"Sucesso." } ] } } |
- De / Para Campos
Elemento | Campo | Descrição |
---|---|---|
identifier | FwXfilial("SA1") + A1_COD+A1_LOJA ou FwXfilial("SA2")+A2_NOME+A2_LOJA | Chave do Cliente ou Fornecedor |
country | A1_PAIS ou A2_PAIS (SYA.YA_SIGLA) | País do Cliente ou Fornecedor (EICA100) Países |
state | A1_EST ou A2_EST | Campo do Estado |
city | A1_MUN ou A2_MUN | Campo do Município |
zipCode | A1_CEP ou A2_CEP | Campo do CEP |
address | A1_END ou A2_END | Campo do endereço, número |
4.2. Envio de Pedidos Para Roteirização
A integração depende dos Pedidos, dos veículos selecionados e dos parâmetros de integração:
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "vehicles":[ { "identifier":" 000001", "speed":80, "weightCapacity":11000, "volumeCapacity":58, "quantity":1 }, { "identifier":" PAM001", "speed":60, "weightCapacity":3220, "volumeCapacity":96, "quantity":1 }, { "identifier":" 000002", "speed":80, "weightCapacity":12500, "volumeCapacity":57, "quantity":1 } ], "routingOptions":{ "capacityCriteria":"WEIGHT", "routingInstantType":"D+1", "minServiceDuration":900000, "maxServiceDuration":7200000, "driverRestTimes":"Default", "considerReturnDistance":"True", "routingType":"ROUTING", "tollCalculation":"False" }, "callbackAuthenticationType":"NONE", "dateCall":"2021-11-04T16:50:38", "callbackURL":"HTTP://179.223.161.99:8084/REST/V1/WSTPRNEOLOG/", "qualifiers":"{\"sistema\":\"PROTHEUS\",\"identifier\":\"04000000108\",\"usuario\":\"Administrador\",\"modulo\":\"OMS\",\"empresa\":\"99\",\"routingType\":\"ROUTING\",\"filial\":\"04\"}", "orders":[ { "identifier":"04543517", "pickupTimeWindowEnd":"2021-11-12T18:00-03:00", "deliveryTimeWindowStart":"2021-11-05T08:00-03:00", "deliveryTimeWindowEnd":"2021-11-12T18:00-03:00", "serviceLoadDuration":null, "serviceUnloadDuration":null, "destination":{ "identifier":" CLISC101", "latitude":-18.85791, "longitude":-41.942810000000001, "name":"CL GOV. VALADARES MG", "country":"BRA", "operation":"UNRESTRICTED" }, "weight":1500, "volume":0.25, "pickupTimeWindowStart":"2021-11-05T08:00-03:00", "origin":{ "identifier":"04-NEPO JUNDIAI - SP-TESTE", "latitude":-19.516919999999999, "longitude":-40.652200000000001, "name":"", "country":"BRA", "operation":"UNRESTRICTED" } }, { "identifier":"04543520", "pickupTimeWindowEnd":"2021-11-12T18:00-03:00", "deliveryTimeWindowStart":"2021-11-05T08:00-03:00", "deliveryTimeWindowEnd":"2021-11-12T18:00-03:00", "serviceLoadDuration":null, "serviceUnloadDuration":null, "destination":{ "identifier":" 00458501", "latitude":-19.361229999999999, "longitude":-40.050609999999999, "name":"CLIENTE LINHARES -ES", "country":"BRA", "operation":"UNRESTRICTED" }, "weight":5000, "volume":0.019008, "pickupTimeWindowStart":"2021-11-05T08:00-03:00", "origin":{ "identifier":"04-NEPO JUNDIAI - SP-TESTE", "latitude":-19.516919999999999, "longitude":-40.652200000000001, "name":"", "country":"BRA", "operation":"UNRESTRICTED" } }, { "identifier":"04543526", "pickupTimeWindowEnd":"2021-11-12T18:00-03:00", "deliveryTimeWindowStart":"2021-11-05T08:00-03:00", "deliveryTimeWindowEnd":"2021-11-12T18:00-03:00", "serviceLoadDuration":null, "serviceUnloadDuration":null, "destination":{ "identifier":" PFISIC01", "latitude":-20.306419999999999, "longitude":-40.350720000000003, "name":"VITÓRIA - ES", "country":"BRA", "operation":"UNRESTRICTED" }, "weight":30, "volume":0.005, "pickupTimeWindowStart":"2021-11-05T08:00-03:00", "origin":{ "identifier":"04-NEPO JUNDIAI - SP-TESTE", "latitude":-19.516919999999999, "longitude":-40.652200000000001, "name":"", "country":"BRA", "operation":"UNRESTRICTED" } } ], "restrictions":{ "maxLoadingStops":1, "maxUnloadingStops":99, "maxDistanceBetweenLoadStops":9000, "allowInterleaving":"False", "maxDistanceBetweenUnloadStops":3000 } } |
- Mensagem de Resposta
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "success":true, "messages":[ { "messageCode":"TPRRT0000", "message":"Sucesso." } ] } |
- Mensagem de Retorno
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "responseDate":"2021-11-04T13:50:38.000-03:00", "version":null, "summary":{ "totalTrips":1, "totalDistance":790.2284089297932, "totalStops":4, "totalVolume":0.27400800000000003, "totalWeight":6530.0, "totalDuration":3.9160278E7, "rejectedOrders":0, "rejectedWeight":0.0, "rejectedVolume":0.0 }, "tripsResults":[ { "sequential":0, "distance":790.2284089297932, "numberOfStops":5, "volume":0.27400800000000003, "weight":6530.0, "duration":39160278, "extraTrip":false, "tollValue":0.0, "considerReturnDistance":true, "vehicle":" 000001", "stops":[ { "sequence":0, "type":"LOAD", "locality":{ "identifier":"04-NEPO JUNDIAI - SP-TESTE", "name":"", "country":"BR", "latitude":-19.51692, "longitude":-40.6522, "operation":"UNRESTRICTED" }, "arrivalTime":"2021-11-05T08:00:00.000-03:00", "departureTime":"2021-11-05T08:15:00.000-03:00", "tollValue":0.0, "distance":0.0, "loadedOrders":[ { "identifier":"04543517", "volume":0.25, "weight":1500.0 }, { "identifier":"04543520", "volume":0.019008, "weight":5000.0 }, { "identifier":"04543526", "volume":0.005, "weight":30.0 } ], "unloadedOrders":[ ] }, { "sequence":1, "type":"UNLOAD", "locality":{ "identifier":" PFISIC01", "name":"VITÓRIA - ES", "country":"BR", "latitude":-20.30642, "longitude":-40.35072, "operation":"UNRESTRICTED" }, "arrivalTime":"2021-11-05T10:00:37.292-03:00", "departureTime":"2021-11-05T10:15:37.292-03:00", "tollValue":0.0, "distance":140.82872152560284, "loadedOrders":[ ], "unloadedOrders":[ { "identifier":"04543526", "volume":0.005, "weight":30.0 } ] }, { "sequence":2, "type":"UNLOAD", "locality":{ "identifier":" 00458501", "name":"CLIENTE LINHARES -ES", "country":"BR", "latitude":-19.36123, "longitude":-40.05061, "operation":"UNRESTRICTED" }, "arrivalTime":"2021-11-05T12:04:01.970-03:00", "departureTime":"2021-11-05T12:19:01.970-03:00", "tollValue":0.0, "distance":144.54840026439211, "loadedOrders":[ ], "unloadedOrders":[ { "identifier":"04543520", "volume":0.019008, "weight":5000.0 } ] }, { "sequence":3, "type":"UNLOAD", "locality":{ "identifier":" CLISC101", "name":"CL GOV. VALADARES MG", "country":"BR", "latitude":-18.85791, "longitude":-41.94281, "operation":"UNRESTRICTED" }, "arrivalTime":"2021-11-05T15:57:57.551-03:00", "departureTime":"2021-11-05T16:12:57.551-03:00", "tollValue":0.0, "distance":291.9018079442051, "loadedOrders":[ ], "unloadedOrders":[ { "identifier":"04543517", "volume":0.25, "weight":1500.0 } ] }, { "sequence":4, "type":"LOAD", "locality":{ "identifier":"04-NEPO JUNDIAI - SP-TESTE", "name":"", "country":"BR", "latitude":-19.51692, "longitude":-40.6522, "operation":"UNRESTRICTED" }, "arrivalTime":"2021-11-05T18:52:40.278-03:00", "departureTime":"2021-11-05T18:52:40.278-03:00", "tollValue":0.0, "distance":212.9494791955932, "loadedOrders":[ ], "unloadedOrders":[ ] } ] } ], "rejections":[ ], "messages":[ ], "qualifiers":"{\"sistema\":\"PROTHEUS\",\"identifier\":\"04000000108\",\"usuario\":\"Administrador\",\"modulo\":\"OMS\",\"empresa\":\"99\",\"routingType\":\"ROUTING\",\"filial\":\"04\"}" } |
- Parâmetros Para o Planejamento que Devem Ser Informados no Envio de Pedidos
TOTVS Planejamento de Rotas (TPR) - Rotina OMSATPR1 - (Grupo OMSATPR1A )
Descrição | Elemento | Regra do elemento | Exemplo |
---|---|---|---|
Critério da capacidade ? | TPRRoutingOptions:capacityCriteria | Tipo de roteirização:
| Peso |
Planejamento para ? | TPRRoutingOptions:routingInstantType | Define o instante a partir do qual as viagens podem ser expedidas:
| D+1 |
Qtd. dias limite p/ entregas ? | TPRRoutingOrders:deliveryTimeWindowEnd | Quantidade de dias para realizar a entrega. Se estiver planejado como D+1, começará a contar a partir do próximo dia. | 2 |
Horário de carregamento ? | TPRRoutingOrders:pickupTimeWindowStart | Horário inicial da janela de carregamento dos Pedidos. | 08:00 |
Funcionamento filial ? | TPRRoutingLocality:operation | Horário de trabalho da Filial. Este parâmetro definirá o início do carregamento dos Pedidos, nas seguintes opções:
| Dias úteis |
Considera retorno p/ filial ? | TPRRoutingOptions:considerReturnDistance | Verifica se é para contabilizar a distância de retorno a origem na roteirização. | Sim |
Qtd. máx. carregamentos ? | TPRRoutingRestrictions:maxLoadingStops | Quantidade máxima de paradas de carregamento por viagem. | 1 |
Km máx. entre carregamentos ? | TPRRoutingRestrictions:maxDistanceBetweenLoadStops | Máxima distância, em Km, entre paradas de carregamento. | 700 |
Km máx. entre entregas ? | TPRRoutingRestrictions:maxDistanceBetweenUnloadStops | Máxima distância, em Km, entre paradas de entregas. | 700 |
Qtd. máx. de entregas ? | TPRRoutingRestrictions:maxUnloadingStops | Quantidade máxima de paradas de entregas por viagem. | 4 |
Tempo mín. de serviço ? | TPRRoutingOptions:minServiceDuration | O montante mínimo do tempo de serviço. Caso a soma dos tempos de carregamento e descarregamento não ultrapassem o valor mínimo, este será utilizado. Valor padrão: 30m | 00:30 |
Tempo máx. de serviço ? | TPRRoutingOptions:maxServiceDuration | O montante máximo do tempo de serviço. Caso a soma dos tempos de carregamento e descarregamento ultrapassem o valor máximo, este será utilizado. Valor padrão: 8h | 04:00 |
Horário final das entregas ? | TPRRoutingOrders:deliveryTimeWindowEnd | Horário final da janela de entregas. | 18:00 |
Funcionamento entregas ? | TPRRoutingLocality:operation | Horário das empresas que receberão as entregas. Este parâmetro definirá a janela de entregas e possui as seguintes opções:
| Dias úteis |
Calcula pedágio ? | tollCalculation | TPR deverá realizar o cálculo do pedágio na roteirização:
| Sim |
Entregas ord. por estado(UF)? | stateReturnForbidden | Quando informado:
| Não |
- Parâmetros Para o Planejamento que Devem Ser Informados no OMSA200 Para Envio de Roteirização TPR
TOTVS Planejamento de Rotas (TPR) - Rotina OMSA200 - (Grupo OMSATPR5 )
Descrição | Elemento | Regra do elemento | Exemplo |
---|---|---|---|
Planejamento para ? | TPRRoutingOptions:routingInstantType | Define o instante a partir do qual as viagens podem ser expedidas:
| D+1 |
Horário de carregamento ? | TPRRoutingOrders:pickupTimeWindowStart | Horário inicial da janela de carregamento dos Pedidos. | 08:00 |
Funcionamento filial ? | TPRRoutingLocality:operation | Informar horário de trabalho da Filial. Este parâmetro definirá o início do carregamento dos Pedidos, nas seguintes opções:
| Dias úteis |
Considera retorno p/ filial ? | TPRRoutingOptions:considerReturnDistance | Verifica se é para contabilizar a distância de retorno a origem na roteirização. | Sim |
Tempo mín. de serviço ? | TPRRoutingOptions:minServiceDuration | O montante mínimo do tempo de serviço. Caso a soma dos tempos de carregamento e descarregamento não ultrapassem o valor mínimo, este será utilizado. Valor padrão: 30m | 00:30 |
Tempo máx. de serviço ? | TPRRoutingOptions:maxServiceDuration | O montante máximo do tempo de serviço. Caso a soma dos tempos de carregamento e descarregamento ultrapassem o valor máximo, este será utilizado. Valor padrão: 8h | 04:00 |
Horário final das entregas ? | TPRRoutingOrders:deliveryTimeWindowEnd | Horário final da janela de entregas. | 18:00 |
Funcionamento entregas ? | TPRRoutingLocality:operation | Horário das empresas que receberão as entregas. Este parâmetro definirá a janela entregas e possui as seguintes opções:
| Dias úteis |
Calcula pedágio ? | tollCalculation | O TPR deverá realizar o cálculo do pedágio na roteirização:
| Sim |
Entregas ord. por estado(UF)? | stateReturnForbidden | Quando informado:
| Não |
- Informações Enviadas dos Veículos (DE / PARA)
Elemento | Campo | Descrição |
---|---|---|
identifier | FwXfilial("DA3") + DA3_COD | Chave do veículo. |
weightCapacity | DA3_CAPACM | Capacidade do veículo, em quilos. |
volumeCapacity | DA3_VOLMAX | Capacidade do veículo, em metros cúbicos. |
speed | DA3_VELOC | Define a velocidade que dos veículos em uma roteirização. |
quantity | 1 | Quantidade de veículos, semelhantes a este, disponíveis. |
tollAxes | DA3_QTDEIX | Quantidade de eixos na ida para cálculo do pedágio. Default 6. |
tollReturnAxes | DA3_QTEIXV | Quantidade de eixos na volta para cálculo do pedágio. Default 4. |
- Informações Enviadas dos Pedidos (DE / PARA)
Elemento | Campo | Descrição |
---|---|---|
identifier | FwXfilial("SC9") + C9_PEDIDO | Os Pedidos são enviados identificados pela filial + código do pedido. |
weight | C9_QTDLIB * SB1.B1_PESBRU | O peso enviado do Pedido é a quantidade liberada multiplicada pelo peso bruto do Pedido liberado. |
volume | (SB5.B5_ALTURLC * SB5.B5_LARGLC * SB5.B5_COMPRLC)*C9_QTDLIB | O volume calculado é baseado nos campos de medidas do produto multiplicado pela quantidade liberada do Pedido. |
pickupTimeWindowStart | Parâmetro Horário de carregamento + Planejamento para ? | O início da janela de carregamento é o horário inicial da Filial e a data depende do parâmetro Agora ou D+1. Quando informado:
|
pickupTimeWindowEnd | Parâmetro Horário final das entregas ? + Qtd. dias limite p/ entregas ? | O prazo de carregamento é o limite da entrega. |
deliveryTimeWindowStart | Parâmetro Horário de carregamento + Planejamento para ? | O início das entregas depende do Funcionamento entregas ?, que significa o horário de trabalho dos clientes e o início de carregamento da carga. |
deliveryTimeWindowEnd | Parâmetro Horário final das entregas ? + Qtd. dias limite p/ entregas ? | O limite da entrega é considerado pelo horário limite das entregas, prazo em quantidade de dias, planejamento do carregamento (Agora, D+1) e a forma de trabalho do cliente (Sem restrição, dias úteis, de manhã, a tarde). |
origin | ||
identifier | SM0->M0_CODFIL - SM0->M0_FILIAL - SM0->M0_NOME | Identificador para integração e apresentação da Filial no mapa de roteirização. |
name | SM0->M0_CODFIL - SM0->M0_FILIAL - SM0->M0_NOME | Identificador para integração e apresentação da Filial no mapa de roteirização. |
country | BRA | País padrão da Filial (Brasil). |
latitude | DAR_LATITU | Informação de coordenadas da Filial (SM0), mantida na tabela de coordenadas geográficas (DAR). |
longitude | DAR_LONGIT | Informação de coordenadas da Filial (SM0), mantida na tabela de coordenadas geográficas (DAR). |
operation | Parâmetro informado em Funcionamento filial OMSATPR1A | Parâmetro de funcionamento da Filial (Sem restrição, dias úteis, de manhã, a tarde), informado antes de enviar os Pedidos para o planejamento via OMSATPR1. |
destination | ||
identifier | FwXfilial("SA1") + A1_COD+A1_LOJA ou FwXfilial("SA2")+A2_NOME+A2_LOJA | Identificador para integração dos cliente ou fornecedores. |
name | A1_NREDUZ ou A2_NREDUZ | Nome do cliente ou fornecedor apresentado no mapa de roteirização. |
country | A1_PAIS ou A2_PAIS | País cadastrado na entidade. |
latitude | DAR_LATITU | Informação de coordenadas do cliente (SA1) ou fornecedor (SA2), mantida na tabela de Coordenadas Geográficas (DAR). |
longitude | DAR_LONGIT | Informação de coordenadas do cliente (SA1) ou fornecedor (SA2), mantida na tabela de coordenadas geográficas (DAR). |
operation | Parâmetro informado em Funcionamento entregas OMSATPR1A | Parâmetro de funcionamento das entregas (Sem restrição, dias úteis, de manhã, a tarde, customizado), informado antes de enviar os Pedidos para planejamento via OMSATPR1. |
5. Funcionalidades Não Atendidas
5.1. Alocação de Veículos
Como a seleção de veículos é baseada na rotina OMSA230 (Alocação de Veículos), não são realizadas validações em veículos.
5.2. Operador Logístico
No momento, a funcionalidade para Operador Logístico ainda não foi implementada na integração.
6. Fluxograma
6.1. Processo de Envio de Pedido de Vendas
draw.io Diagram | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
6.2. Processo de Callback da Roteirização (Rotina em JOB)
draw.io Diagram | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
6.3. Processo de Alteração de Rota / Mapa
draw.io Diagram | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
6.4. Callback Processo de Alteração de Rota / Mapa
draw.io Diagram | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
8. Customizações Disponíveis
8.1 Como Executar a API de Geolocalização Via User Function
É possível gerar as geolocalizações das entidades de forma customizada. Da mesma forma, ao enviar os Pedidos para integração via OMSATPR1 ou OMSA200, a geolocalização a ser considerada será cadastrada na tabela DAR. Caso contrário, poderá ser utilizado o Ponto de Entrada OMSTPR01 para alterar a geolocalização das entidades de entrega.
Segue a documentação oficial da API: Integração de Geolocalização - Síncrona.
Exemplo de Utilização da API em ADVPL:
Bloco de código | ||||
---|---|---|---|---|
| ||||
#include 'totvs.ch' #include "tbiconn.ch" User Function XGETGEO() Local cEmpLog := "99" Local cFilLog := "01" Local cModLog := "OMS" Local oJson := JsonObject():New() Local oQualif := JsonObject():New() Local oAddress := JsonObject():New() Local oResp := Nil Local aHeader := {} Local cQualif := "" Local cParams := "" Local oRest := FwRest():New('https://planejamentorotas.totvs.com/') Local lRet := .F. PREPARE ENVIRONMENT EMPRESA cEmpLog FILIAL cFilLog MODULO cModLog //-- Elemento livre para controle interno oQualif["elementolivre1"] := "conteudo para controle Y" oQualif["elementolivre2"] := "conteudo A" oQualif["elementolivre3"] := "conteudo X" cQualif := oQualif:ToJson() //Monta header Aadd(aHeader, "Accept: application/json" ) Aadd(aHeader, "Content-Type: application/json" ) //cole seu token aqui ou faça um seek para obter a DLV_TOKEN Aadd(aHeader, "TPR_AUTHORIZATION: " + '321f3-f32f32-f32-9cdd-e6d9f10ca60943f64ec1-e9f8-f32f32-a0b2-f' ) oJson["dateCall"] := FwTimeStamp(3,dDataBase, Time() ) oJson["system"] := cModulo oJson["qualifiers"] := cQualif //Endereco a ser pesquisado oAddress["identifier"]:= 'Código do cliente' oAddress["country"] := 'BRA' oAddress["state"] := 'SC' oAddress["city"] := 'JOINVILLE' oAddress["zipCode"] := '89218-100' oAddress["address"] := 'Avenida Santos Dumont, 831' oJson["address"] := oAddress cParams := oJson:ToJson() oRest:SetPath( "v1/tpr-geolocation-sync" ) oRest:SetPostParams( EncodeUTF8(cParams) ) lRet := oRest:Post( aHeader ) If lRet oResp := JSonObject():New() oResp:fromJson(Decodeutf8(oRest:GetResult())) conout(oResp["geolocationResult"]["latitude"]) //Retorno da latitude conout(oResp["geolocationResult"]["longitude"]) //Retorno da longitude Else conout(oRest:GetLastError()) conout(oRest:GetResult()) EndIf RESET ENVIRONMENT Return |