INTEGRAÇÃO TOTVS OMS X TOTVS PLANEJAMENTO DE ROTAS

X MÓDULO OMS PROTHEUS

(TPR)

Índice

Contexto de negócio

O TOTVS OMS disponibiliza uma funcionalidade que permite enviar pedidos ou itens de pedidos de vendas liberados, veículos, parâmetros de entregas ao TPR - TOTVS Planejamento de Rotas, que realizará a otimização dos dados recebidos para compor a carga e a melhor rota de entrega dos Pedidos.

Sistemas Envolvidos

Protheus - Seleção de pedidos, seleção de veículos, parametrização, visualização de pedidos a roteirizar, visualização de pedidos rejeitados, visualização de pedidos processados com carga, visualização do json de envio, visualização do json de resposta, visualização do json de retorno, geração da carga de acordo com a viagem retornada pela integração, validações de alterações de pedidos, aviso da exclusão da roteirização ao estornar pedido, manter geolocalizações dos clientes para planejamento de rotas.
Neolog/TPR - Validações de entrada de informações para processamento de geolocalização, retornar latitude e longitude para a api consumidora da geolocalização, validações de entrada de informações para processamento de roteirização, retornar para a api consumidora se fará o processamento da roteirização, realizar o processamento de roteirização e retornar para a api consumidora as viagens geradas, retornar mapa de acordo com a viagem gerada.

Integração

A integração com o TOTVS Planejamento de Rotas deve automatizar o processo de geração de cargas. No qual o usuário seleciona pedidos de vendas liberados e veículos para que via integração, seja definida a melhor organização de cargas e a melhor ordem e rota de entregas desses pedidos nos clientes.

Premissas para a integração:

Para realizar a integração é necessário o preenchimento do endereço completo dos clientes (Endereço com número, CEP, bairro, cidade, estado e país) ou gerar geolocalizações para as entidades no programa (TMSAO15).
Veículos cadastrados;

Pedidos gerados e liberados;

Escopo

O escopo desta integração abrange a Geração da Carga e a visualização do Mapa no TOTVS OMS na rotina Montagem de Carga - OMSA200. A Geração da Carga ocorre com base nos pedidos de vendas liberados, veículos e parâmetros de entrega enviados ao TPR. A visualização do Mapa contém a melhor rota para a entrega, apresentando a quilometragem que será realizada, o tempo que será consumido, o volume e o peso do serviço.

O OMS não gera roteirização sem o envio dos pedidos ao TPR (Totvs Planejamento de Rotas).

Pré-requisitos instalação/implantação/utilização

Informações
Prezado cliente, esta Integração fica disponível de forma nativa somente no Release 12.1.37 do Protheus conforme Ciclo de Vida de Software - TOTVS Linha Protheus. Caso tenha interesse em adquirir esta solução nas Release 12.1.27 ou 12.1.33 do Protheus, por gentileza entre em contato com nosso suporte solicitando as informações a seguir

Para realizar a integração é necessário possuir os dicionários, novos programas ou atualizações dos programas do Faturamento, OMS e TMS.

Importante!
Aplique o pacote conforme sua versão do Sistema.

Utilize o Pacotes de Atualização - TOTVS OMS - P12 para atualizar as rotinas do TOTVS OMS, aceitando somente os fontes atualizados.
Utilize o Pacotes de Atualização - TOTVS Logística TMS - Linha Protheus - P12 para atualizar os fontes aceitando somente os fontes atualizados.
Utilize o Pacote Fat...

Módulo	Programa	Descrição
Faturamento	FATXFUN.PRX	Funções genéricas FAT
Faturamento	MATA410.PRX	Pedidos
Faturamento	MATA461.PRX	Preparação dos Documentos de Saída
Faturamento	MATV410.PRW	Funções para o Estorno de Pedidos
OMS	OMSA200.PRW	Montagem de Carga
OMS	OMSATPR1.PRW	Envio de Pedidos - TPR (Menu)
OMS	OMSATPR1A.PRW	Funções do Envio de Pedidos - TPR
OMS	OMSATPR2.PRW	Processamento do callback do retorno das viagens/carga - TPR
OMS	OMSATPR3.PRW	Visualização do mapa da carga gerada (OMSA200 > Ações Relacionadas > Visualizar Mapa)
OMS	OMSATPR4.PRW	Validações para a alteração e estorno de pedidos integrados com o TPR
OMS	OMSXFUN.PRW	Funções genéricas OMS
TMS	TMSAC18.PRW	Métodos de Envio - Integração Planejamento de Rotas
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)
TMS	TMSAC20.PRW	Configuração Planejamento de Rotas: Rotina principal para realizar o cadastro e habilitar a integração Totvs Planejamento de Rotas (TPR).
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.
TMS	TMSAC24.PRW	Montagem e visualização do Mapa
TMS	TMSAC25.PRW	Montagem e visualização do Mapa
TMS	TMSAO15.PRW	Cadastro Referência Geográfica
TMS	TMSAO48.PRW	Integração Rota Inteligente
TMS	TMSO46API.PRW	Métodos CallBack Planejamento de Rotas

Para a integração é necessário realizar algumas configurações no appserver.ini

Configuração do REST do Protheus (appserver.ini)

Bloco de código

title	Configuração REST
collapse	true

;************************************
;*** 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 (appserver.ini)

Bloco de código

title	Configuração HTTP
collapse	true

[HTTP]
ENABLE=1
PATH=C:\Bases\environment1\data\web  (Pasta que contém os arquivos index.html e tprchannel.js)
PORT=8021   
INSTANCES=1,10    
SESSIONTIMEOUT=60
INSTANCENAME=WS_HTTP

[10.173.11.38:8021/ws] (Informação importante para apresentar o mapa. O campo URL Mapa HTML do programa TMSAC20, é realizado com "http://" + "10.173.11.38:8021/ws" + "/ws/index.html").
ENABLE=1
PATH=C:\Bases\environment1\data\web  (Pasta que contém os arquivos index.html e tprchannel.js)
ENVIRONMENT=environment1
INSTANCENAME=WS_OMSCARGA
RESPONSEJOB=JOB_WS_OMS
DEFAULTPAGE=wsindex.apw

O ip e porta "10.173.11.38:8021" são exemplos para o cadastro. O ip e porta cadastrado nessa sessão precisam ser visualizados em toda a rede de acesso smartclient. Caso exista algum bloqueio de rede, o mapa não será apresentado no Protheus.

Configurar Portais e Webservices (appserver.ini)

Bloco de código

title	Configuração JOB
collapse	true

[JOB_WS_OMS]
TYPE=WEBEX
ENVIRONMENT=environment1
INSTANCES=1,10               
INSTANCENAME=JOB_WS_OMS
ONSTART=__WSSTART
ONCONNECT=__WSCONNECT
PREPAREIN=All
SIGAWEB=WS

Parâmetros utilizados (SIGACFG):

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. Informar .F. após a implantação. Incluir no ini do REST, na sessão do enviroment, a chave FWTRACELOG=1
MV_HVERAO	Verifica se o local fisico do servidor está em Horário de Verão .F. Não / .T. Sim (MV_HVERAO)	.F.
MV_CDTPOP	Indica qual o código de operação será enviada ao TOTVS GFE na geração da carga. O mesmo deve ser cadastrado primeiramente no TOTVS GFE e vinculado. Preenche o campo DAK_CDTPOP.
MV_CDCLFR	Código da Classificação de Frete Padrão usado na importação de Documentos de Carga. Preenche o campo DAK_CDCLFR.
MV_OMSENTR	Define o número de incremento do campo Sequência de Entrega (DAK_SEQENT) na Montagem de Cargas, deve ser informado o conteúdo padrão igual a 5 (cinco).	5

Arquivos relacionados ao mapa (data/web):

Verifique se os arquivos index.html e tprchannel.js constam na pasta web conforme PATH configurado (PATH=C:\Bases\environment1\data\web).

Atualizar o menu do OMS

sigaoms.xnu

Programa	Menu
OMSATPR1	Envio de Pedidos
TMSAO15	Cadastro Referência Geográfica
TMSAC19	Painel Integração Planejamento de Rotas
TMSAC23	Controle de Integração Planejamento de Rotas
TMSAC20	Configuração Planejamento de Rotas

Atualizar o help

hlppor.txt

Aplicar o pacote de dicionários do TMS 9506 para que sejam criadas as tabelas DMR e DMS. O pacote criará campos nas tabelas DLU e DLV.

Informações sobre os campos do TMS em DT DLOGTMS02-17080 Integração SIGATMS x Planejamento de Rotas (TPR) - DETALHAMENTO DA ATUALIZAÇÃO DE DICIONÁRIO CONFORME ABAS

Aplicar o pacote de dicionários do OMS 9560 para que sejam criadas campos nas tabelas DA3 e DAK. O pacote criará o parâmetro MV_TPRCLOG e os campos abaixo:

Campo novo:

Campo	DA3_VELOC
Tipo	Numérico
Tamanho	6
Decimal	0
Formato
Título	Veloc. média
Descrição	Velocidade média
Usado	Sim
Obrigatório	Não
Browse	Sim
Opções
When
Relação
Val. Sistema
Help	Informar a velocidade média do veículo.

Campo novo:

Campo	DAK_INTTPR
Tipo	Caractere
Tamanho	1
Decimal	0
Formato
Título	Int. TPR
Descrição	Integração TPR
Usado	Sim
Obrigatório	Não
Browse	Não
Opções	1=Carga gerada pelo TPR
When
Relação
Val. Sistema
Help	Informa se a carga foi gerada através da integração com o TPR (Totvs Planejamento de Rotas).

Campo novo:

Campo	DAK_VIAEXT
Tipo	Caractere
Tamanho	1
Decimal	0
Formato
Título	Viagem Extra
Descrição	Viagem extra do TPR
Usado	Sim
Obrigatório	Não
Browse	Não
Opções	1=Sim, 2=Não
When
Relação	"2"
Val. Sistema
Help	Indica se a viagem gerada pelo TPR é uma 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.

Parâmetro novo:

Campo	Valor
X6_VAR	MV_TPRCLOG
X6_TIPO	L
X6_DESCRIC	Define a visualização do log de operações do TPR no ConsoleFile configurado.
X6_CONTEUD	.T.

DA3_VELOC: Neste campo, poderá ser informada a velocidade média do veículo via rotina OMSA060 (Cadastro de Veículos)

DAK_INTTPR: Ao aplicar o pacote, marcar via SIGACFG como usado. Este campo informará se a origem da geração da carga será via TPR.

DAK_VIAEXT: Ao aplicar o pacote, marcar via SIGACFG como usado. Este campo informará se a carga gerada é uma viagem extra.

Configurar as URLs de integração TPR - (Totvs Planejamento de Rotas) - Passo a passo TMSAC20

Após a geração e ativação do token no passo anterior via TMSAC20. Ao alterar um cliente via MATA030, será realizada uma integração para obter a geolocalização com base no cadastro do endereço.

A geolocalização pode ser incluída/alterada ou visualizada pelo programa de Referência Geográfica (TMSA015 - SIGATMS)

Integrações

A integração é realizada em apis REST. Abaixo segue um resumo das integrações:

Criaçã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(1) e recebe uma resposta do recebimento do TPR(2). 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:

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) caso o Clientenão possua coordenadas geradas (TMSAO15 - Tabela DAR).

Exemplo de envio:

Bloco de código

title	Json de envio ao TPR
collapse	true

{
   "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

title	Json de retorno do TPR
collapse	true

{
   "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

2 - Envio de pedidos para roteirização: A integração depende dos pedidos, dos veículos selecionados e os parâmetros de integração:

Bloco de código

title	Json de envio ao TPR
collapse	true

{
   "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",
      "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\",\"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

title	Json de resposta do TPR
collapse	true

{
   "success":true,
   "messages":[
      {
         "messageCode":"TPRRT0000",
         "message":"Sucesso."
      }
   ]
}

Mensagem de Retorno:

Bloco de código

title	Json de retorno do TPR
collapse	true

{
   "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\",\"filial\":\"04\"}"
}

Parâmetros para o planejamento que devem ser informados no Envio de Pedidos - Totvs Planejamento de Rotas (TPR) - Programa 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: "Agora" Inicio das viagens na primeira hora factível a partir do momento da roteirização mais uma hora. "D+1" Inicio das viagens para amanhã no primeiro horário factível de carregamento.	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: Sem restrição (00:00-23:59 de Dom-Sab), Dias úteis (08:00-17:59 de Seg-Sex), De manhã (08:00-11:59 de Seg-Sex), À tarde (14:00-17:59 de Seg-Sex).	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	Informar horário das empresas que receberão as entregas. Este parâmetro definirá a janela entregas e possui as seguintes opções: Sem restrição (00:00-23:59 de Dom-Sab), Dias úteis (08:00-17:59 de Seg-Sex), De manhã (08:00-11:59 de Seg-Sex), À tarde (14:00-17:59 de Seg-Sex).	Dias úteis

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.

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) informado antes de enviar os pedidos para planejamento via OMSATPR1

Processo de utilização

TMSAC20 (Configuração Planejamento de Rotas)

Parametrizar das URLs e gerar o token.

MATA030 (Cadastro de Clientes)

Verificar os endereços dos clientes e país.

EICA100 (Países)

Verificar a sigla BRA para o país Brasil.

OMSA060 (Veículos)

Preencher o campo novo DA3_VELOC. Caso não seja preenchido, o TPR considerará 30km/h.

TMSAO15 (Coordenadas Geográficas)

Verificar as coordenadas geradas para os clientes e localização no mapa.

Informações importantes:

O programa permite que sejam geradas as coordenadas para o cliente mesmo que ele não possua endereço cadastrado.

É possível alterar as coordenadas geradas de um cliente através do marcador no mapa. Deste modo, pode destacar o ponto exato para o endereço caso não exista formas de geolocalizá-lo via api.

MATA010 (Produtos)

Verificar os campos B1_PESO, B1_PESBRU, B5_ALTURLC, B5_LARGLC, B5_COMPRLC

MATA410 (Pedidos)

Gerar pedidos para os clientes (liberar).

OMSATPR1 (Envio de Pedidos - Totvs Planejamento de Rotas)

Selecionar pedidos, selecionar veículos, informar parâmetros (F6).

Ao enviar os pedidos, o browse de pedidos será atualizado e este pedidos aparecerão no 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 clicar em "Integrações do Item" no programa OMSATPR1 (Envio de Pedidos) ou acessar diretamente a rotina TMSAC19 (Consulta Planejamento de Rotas).

O programa TMSAC19 (Consulta Planejamento de Rotas) apresenta o status da integração e bem como o resultado de cada item. 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:

Pendente (quando o item foi enviado e está aguardando retorno do planejamento TPR)

Processado (quando houve retorno do TPR e foi gerada carga (viagem) para o item. Apresenta o código da carga gerada para o item. Permite visualizar o mapa através do programa. Existem 2 possibilidades: Todas as cargas geradas através do botão do browse superior "Visualizar mapa" ou apenas a carga relacionada a um item (DMS), clicando em "Visualizar mapa" no botão do browse inferior.

Rejeitado (quando houve retorno do TPR, mas o mesmo informa que por regra de negócio informada para planejamento é impossível gerar viagem para o item). Exemplo: a capacidade do veículo é menor do que qualquer um dos pedidos selecionados.

Falha no processamento (quando houve alguma inconsistência no ERP que não permitiu o processamento com os dados de retorno). Apresenta o motivo da rejeição do TPR. Exemplo: quando o Protheus não foi configurado corretamente (patch ou dicionários)

O TMSAC19 permite o cancelamento do envio para a alteração dos pedidos através do botão "Cancelar Envio". A alteração do envio não será realizada no TPR. Este cancelamento apenas desconsidera qualquer resultado do planejamento.

No programa, é possível acionar o jsons gerados na API de roteirização através da aba "Controle de Integração". Esta aba abre o programa TMSAC23 (Controle de Integração).

O programa 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 e 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 é necessário clicar 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).

Informações importantes:

O ponto 1 será sempre a partida (filial).

O retorno para a filial considera mais um ponto de parada.

Uma carga roteirizada pode ser alterada, mas perderá o mapa gerado.

O estorno na carga liberará os itens dos pedidos da carga para serem utilizados em outro planejamento no OMSATPR1 (Envio de Pedidos).

O motorista pode ser informado depois da carga gerada.

O campo DAK_INTTPR informa se a origem da carga é no TPR.

O campo DAK_VIAEXT informa se é uma carga/viagem extra.

O campo de time service é calculado via integração com base na subtração da data/hora de saída da entrega - data/hora de saída de chegada na entrega.

Operações em pedidos que possuem roteirização

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.

Páginas filhas

Versões comparadas

Versão antiga 27

Nova versão 28

Chave

INTEGRAÇÃO TOTVS OMS X TOTVS PLANEJAMENTO DE ROTAS

(TPR)

Contexto de negócio

Sistemas Envolvidos

Integração

Escopo

Pré-requisitos instalação/implantação/utilização

Integrações

Processo de utilização

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 27

Nova versão 28

Chave

INTEGRAÇÃO TOTVS OMS X TOTVS PLANEJAMENTO DE ROTAS

(TPR)

Contexto de negócio

Sistemas Envolvidos

Integração

Escopo

Pré-requisitos instalação/implantação/utilização

Integrações

Processo de utilização