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 desse documento.
Mais informações sobre como será realizada a montagem da carga/sequenciamento da entrega podem ser consultados em: TOTVS Planejamento de Rotas.
2. Instalação / Configuração
Informações | ||
---|---|---|
| ||
Para mais informações sobre esta licença entre em contato com o ESN - Especialista de Soluções de Negócios. Esta funcionalidade será disponibilizada oficialmente no Release 12.1.2210 do Protheus, conforme Ciclo de Vida de Software - TOTVS Linha Protheus. Entretanto, já é possível utilizar a mesma estando nos Releases 12.1.27 ou 12.1.33 do Protheus, pois basta baixar os pacotes de Expedição Contínua dos módulos: OMS, TMS e FAT. Aplique o pacote da expedição contínua (Expedição Contínua Protheus) conforme a versão do seu Release, aceitando somente os fontes atualizados.
Aplique os pacotes de dicionário do TMS 009506 e 009880 conforme disponibilizado na documentação Integração SIGATMS x Planejamento de Rotas (TPR) Aplique o pacote para pedágio e roteirização via OMSA200 com carga montada: Pacote_pedagio_roteirizacao_OMSA200.zip Aplique também o pacote 010430 com melhorias TPR para validações de alteração de veículo na carga. Aplique o pacote 010703 e o 010786 pacote com as implementações de Regras de Entrega, Restrições de Veículos e Entregas Ordenadas por Estado(UF)
|
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) | 15/06/2022 08:31:13 |
OMS | OMSATPR1A.PRW | Funções do Envio de Pedidos - TPR. | 27/06/2022 |
OMS | OMSATPR2.PRW | Processamento do CallBack do retorno das viagens/carga - TPR. | 15/06/2022 19:09:30 |
OMS | OMSATPR3.PRW | Visualização do mapa da carga gerada (OMSA200 > Ações Relacionadas > Visualizar Mapa). | 21/06/2022 09:54:30 |
OMS | OMSATPR4.PRW | Validações para a alteração e estorno de pedidos integrados com o TPR. | 24/05/2022 13:42:41 |
OMS | OMSATPR5.PRW | Envio de roteirização TPR via OMSA200 | 27/06/2022 |
OMS | OMSATPR6.PRW | Recebimento do callback de roteirização via OMSA200 | 24/05/2022 13:42:41 |
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. | 27/06/2022 |
TMS | TMSAC19.PRW | Painel Integração Planejamento de Rotas (TPR): Rotina que armazenará as informações referentes ao envio de informações para a integração TOTVS Planejamento de Rotas (TPR). | 21/10/2021 15:44:14 |
TMS | TMSAC20.PRW | Configuração Planejamento de Rotas: Rotina principal para realizar o cadastro e habilitar a integração TOTVS Planejamento de Rotas (TPR). | 24/11/2021 08:36:16 |
TMS | TMSAC23.PRW | Controle de Integração Planejamento de Rotas: Rotina que armazenará as informações enviadas e recebidas. Toda a integração é enviado um arquivo no formato JSON e esse arquivo é armazenado na tabela DLU - Controle Integração Roteirizador. | 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. | 23/05/2022 17:38:18 |
TMS | TMSAO15.PRW | Cadastro de Referência Geográfica. | 24/06/2022 16:12:06 |
TMS | TMSAO48.PRW | Integração Rota Inteligente. | 03/03/2022 11:02:53 |
TMS | TMSO46API.PRW | Métodos CallBack Planejamento de Rotas. | 15/06/2022 08:28:21 |
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 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 conforme documentação: Como atualizar help no Protheus
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 de menu 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. Pode ser reutilizado um Appserver ou gerar outro Appserver para receber as integrações REST.
Também é necessário realizar 3 blocos de configurações dentro do Appserver.ini, conforme exemplos a seguir.
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 |
Configurações 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 | ||
---|---|---|
| ||
|
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)
Campos
Informações | ||
---|---|---|
| ||
Assinale, via SIGACFG, os seguintes campos como usado:
|
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 Enviroment, 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. Caso não seja informada, assumimos o campo DLV_URLCAL + /NEWROUTE |
MV_OMSPROT | Na integração TPR, ao selecionar funcionamento de entregas customizadas, define o funcionamento padrão para clientes sem regras de entrega. | Default "1" "1" = Sem restrição |
/ "2" = Dias úteis |
/ "3" = De manhã |
/ "4" = À tarde Se vazio, informa erro de integração caso o cliente não possua 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 .F. Não / .T. Sim (MV_HVERAO) | |
MV_CDTPOP | Indica qual código de operação será enviado ao TOTVS GFE, na geração da carga. 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). Deve ser informado 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 rotina TMSAC20 (Config. Planejamento de Rotas).
2.6.2. Acesse Atualizações > Planejamento de Rotas > Config. Planejamento de Rotas (TMSAC20) e realize as parametrizações conforme descrito abaixo:
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 confirmar 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.
Informações | ||
---|---|---|
| ||
|
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 web-service 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.ini em Configurações HTTP.
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). Usar HTTPS://PLANEJAMENTOROTAS.TOTVS.COM/V1/TPR-TOKEN-CREATION
URL Roteirização: URL disponibilizada pelo TPR para controle dos serviços de Roteirização do TOTVS Planejamento de Rotas (TPR). Usar 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). Usar 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 do TOTVS Planejamento de Rotas (TPR). Usar HTTPS://PLANEJAMENTOROTAS.TOTVS.COM/V1/TPR-GEOLOCATION
Os campos Token, Data Token e Hora Token serão preenchidos automaticamente pelo retorno do 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.
Essa 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 deseja enviar para roteirização.
Selecione os veículos que deseja considerar 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 através do cadastro do veículo.
Informe os parâmetros para roteirização;
Clique em Enviar. Neste momento os pedidos e a roteirização ficarão no status pendente até o retorno da roteirização.
Caso necessário, clique em Integrações do Item para visualizar o status do envio e todos os itens de pedidos enviados para 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 seu status. 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 cliente e clique em Confirmar;
3.6. Como Realizar Roteirização Via OMSA200
Acesse o OMSA200 (Montagem de Carga) com a carga montada e clique em Carregamento > Associar Veículo. Informe o Veículo da carga
2. 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 através do cadastro do veículo.
3. Informe os parâmetros para planejamento da rota em Outras Ações > Parâmetros Roteirização TPR.
4. Clique em Outras Ações > Planejar Roteirização TPR.
5. Aguarde alguns minutos.
Caso a filial e os clientes não estejam 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 criar um ponto de passagem na roteirização:
Acesse o programa OMSA200 - (Montagem de Carga)
Clique na carga roteirizada e após selecione a opção Outras Ações > Visualizar Mapa TPR
Clique no botão "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 no botão "Atualizar" ou pressione "F5" para atualizar os dados da roteirização.
3.8. Como alterar um ponto de entrega na roteirização:
Acesse o programa OMSA200 - (Montagem de Carga)
Clique na carga roteirizada e após selecione a opção Outras Ações > Visualizar Mapa TPR
Clique no botão "Alterar localidade" no mapa
Mova o ponto do mapa que deseja alterar a localidade exata e confirme.
Aguarde alguns segundos e clique no botão "Atualizar" ou pressione "F5" para atualizar os dados da roteirização.
3.9. Como alterar a ordem das entregas na roteirização:
3.10. Como funcionam as restrições de Janelas de Entrega na roteirização TPR:
Para ativar a funcionalidade é necessário selecionar 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 "OMSA200 - Montagem de Carga".
Para a integração o cadastro das regras e exceções nos programas OMSA120(Regras de Entregas) e OMSA350 (Calendários-Janelas de Entregas) é limitado. São consideradas as regras para os clientes e exceções para os veículos.
Importante: O parâmetro MV_OMSPROT, define como será o "funcionamento das entregas" padrão caso o cliente não possua Janelas de Entrega cadastradas. Se o parâmetro estiver vazio, o TPR informará que o cliente não possui Janelas de Entrega para roteirização.
3.10.1 - Cadastro de regras para cliente(s)
- Informar o grupo de clientes ou o cliente/loja da regra.
- Selecionar ou não um calendário. Caso seja selecionado, este deve ser do tipo Semanal, no qual são informados os dias da semana de trabalho. Caso não seja informado o calendário, consideramos todos os dias da semana com os horários preenchidos.
- Informar 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 validados 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 escolher a opção "Funcionamento entregas" = "Customizado" para validar veículos.
- Informar o grupo de clientes ou o cliente/loja da regra ou exceção para veículos.
- Ao informar o veículo, este não será considerado na roteirização TPR para este cliente ou grupo de clientes.
- Ao informar o grupo de veículos, estes não serão considerados na roteirização TPR para este cliente ou grupo de clientes.
3.11. É possível 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:
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 clientes e o país. |
EICA100 - Países | Verifique a sigla BRA para o país Brasil. |
OMSA060 - Veículos | Informe o novo campo DA3_VELOC. Se este campo não for preenchido, o TPR considerará 30km/h. Informe o novo campo DA3_QTDEIX. Quantidade de eixos na ida para cálculo do pedágio. Default 6. Informe o novo campo DA3_QTEIXV. Quantidade de eixos na volta para cálculo do pedágio. Default 4. |
TMSAO15 - Coordenadas Geográficas | Verifique as coordenadas geradas para os clientes e a localização no mapa. Importante
|
MATA010 - Produtos | Verifique os campos B1_PESO, B1_PESBRU, B5_ALTURLC, B5_LARGLC e B5_COMPRLC. |
MATA410 - Pedidos | Gere os pedidos para os clientes e libere. |
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 este pedidos aparecerão com o status 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 o status da integração, bem como, o resultado de cada item, sendo que os itens são gravados separadamente através 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 nos seguintes status:
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 entregas, 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). Importante
|
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,
E 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 cliente cadastrado (MATA030).
Integração executada ao alterar o cliente via MATA030 (Cadastro de Clientes) ou via Envio de Pedidos - TPR (OMSATPR1), quando o Cliente 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, VOLUME ou AMBOS. | 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 | 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 |
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 entregas e possui as seguintes opções:
| Dias úteis |
Calcula pedágio ? | tollCalculation | Sim/Não: Informar se o TPR deverá realizar o cálculo do pedágio na roteirização | Sim |
Entregas ord. por estado(UF)? | stateReturnForbidden | Se informado "Sim", não permitirá que a rota faça alternância de entregas entre estados. Se informado "Não", a roteirização buscará pela melhor rota e se necessário haverá alternância de entrega entre estados. | 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 | Sim/Não: Informar se o TPR deverá realizar o cálculo do pedágio na roteirização | Sim |
Entregas ord. por estado(UF)? | stateReturnForbidden | Se informado "Sim", não permitirá que a rota faça alternância de entregas entre estados. Se informado "Não", a roteirização buscará pela melhor rota e se necessário haverá alternância de entrega entre estados. | 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" + parâmetro "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. Se preenchido Agora, o planejamento somará uma hora para as entregas do mesmo dia. Se preenchido D+1, o carregamento será para o próximo dia, de acordo com a forma de trabalho da filial (Sem restrição, dias úteis, de manhã, a tarde). |
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" + parâmetro "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 através do 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. |
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 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 (em Desenvolvimento)
draw.io Diagram | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
6.4. CallBack Processo de Alteração de Rota / Mapa (em Desenvolvimento)
draw.io Diagram | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|