Totvs Planejamento de Rotas

Árvore de páginas

Versões comparadas

Versão antiga 5

changes.mady.by.user Julio Vinicius Oliveira dos Santos

Gravado em

comparado com

Nova versão Atual

changes.mady.by.user Vanessa Aparecida Martins de Melo

Gravado em

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.
Aviso
titleIMPORTANTE
  • A integração TOTVS OMS x TOTVS Planejamento de Rotas (TPR) será descontinuada no próximo release (Outubro/2023).

Introdução

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision1
diagramNameTPR_Roteirizacao_FE
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth480


Sistemas Envolvidos

Integração

  • Formato Excel e JSON, para maiores detalhes consulte os Exemplos.

Escopo

  • Integração via front end, compostas pela chamada e pelo retorno, nestas, receberemos uma lista pedidos e, quando possível, retornaremos viagens via rotas via importação e exportação de arquivos;

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

Para clientes Protheus versão xxxxxx;

  • Para clientes Datasul versão xxxxxx;Para todos os clientes, contratação do trial via TOTVS Store.

Layout de Requisição

TPRRouting

TPR

Campo

Tipo

Obrigatório

Tamanho

Descrição

Validações

Exemplos

dateCallDate TimeSimData da criação da chamada no sistema externo.Formato ISO8601.2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZDsystemStringNão4096Identificador do sistema que fez a chamada.

Texto Livre.ProtheusversionStringNão4096Versão do sistema externo.Texto Livre.12.36.1qualifiersObjectNão4096String chave valor.Formato JSON.{"Usuário": "Pedro de Alcântara", "Perfil": "Analista"}callbackURLStringSim4096URL de Callback.Início com "https://".
ordersTPROrders
callbackAuthenticationTypeStringSim4096Tipos de autenticação: BASIC, NONEOpções: BASIC, NONE.NONEcallbackAuthenticationValueStringNão4096Texto de acordo com formato indicado.Texto Livre.QWxhZGRpbjpvcGVuIHNlc2FtZQ==ordersTPRRoutingOrders
[]Sim
Lista de pedidos a serem roteirizados.-Tabela abaixo
vehicles
localities
TPRRoutingVehicles
TPRLocality[]Sim
Lista de veículos disponíveis para a roteirização

Localidades dos pedido.
Tabela abaixorestrictionsTRPRoutingRestrictionsSimRestrições de roteirização.Tabela abaixooptionsTPRRoutingOptionsSimOpções de roteirização.
-
Tabela abaixo

Âncora
TPRRoutingOrdersTPROrdersTPRRoutingOrders
TPROrders

TPRRoutingOrders
TPROrders, tipo de dado utilizado nas integrações do
TPRserviceUnloadDurationLongNão
Front-End
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
identifierStringSim4096Identificador do pedido.

Texto livre, deve se único dentro da chamada.

"Entrega Carrefour"

"PED00133"

weightDoubleNão
Peso total os itens do pedido em quilos.

Se preenchido, deve ser maior ou igual a zero;

Validado de acordo com o campo "capacityCriteria";

Se não existirem veículos que suportem este pedido sozinho  na disponibilidade, ele será rejeitado.

25000
volumeDoubleNão
Volume total dos itens do pedido em metros cúbicos.

Se preenchido, deve ser maior ou igual a zero;

Validado de acordo com o campo "capacityCriteria";

Se não existirem veículos que suportem este pedido sozinho  na disponibilidade, ele será rejeitado.

5000
pickupTimeWindowStartDate TimeSim
Início da janela de carregamento.

Formato ISO8601;

PickupStart deve ser anterior a PickupEnd, se ambos forem preenchidos;

PickupStart deve ser anterior ou igual a DeliveryStart , se ambos forem preenchidos;

PickupStart deve ser anterior a DeliveryEnd e ambos devem ser preenchidos.

"2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD"
pickupTimeWindowEndDate TimeNão
Final da janela de carregamento.Formato ISO8601."2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD"
deliveryTimeWindowStartDate TimeNão
Início da janela de entrega.

Formato ISO8601.

"2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD"
deliveryTimeWindowEndDate TimeSim
Final da janela de entrega.

Formato ISO8601;

DeliveryEnd deve vir posterior de DeliveryStart se ambos forem preenchidos;

DeliveryEnd deve vir posterior  ou igual de PickupEnd se ambos forem preenchidos;

DeliveryEnd deve vir posterior de PickupStart e ambos devem ser preenchidos.

"2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD"
serviceLoadDurationLongNão

Tempo de carregamento do pedido em milissegundos.

Se preenchido, deve ser maior que zero, em Milissegundos.

Se não informado, ou menor que 30 minutos serão considerados 30 minutos de serviço;

Se a soma do serviço for maior que 8 horas serão consideradas 8 horas de serviço;

3600000 [ms]
serviceUnloadDurationLongNão

Tempo de descarregamento do pedido em milissegundos.

Se preenchido, deve ser maior que zero, em Milissegundos.
3600000 [ms]

Se não informado, ou menor que 30 minutos serão considerados 30 minutos de serviço;

Se a soma do serviço for maior que 8 horas serão consideradas 8 horas de serviço;

Se preenchido, deve ser maior que zero, em Milissegundos.
3600000 [ms]
origin
TPRRoutingLocality
StringSim
Localidade

Identificador da localidade de origem do pedido.-Tabela abaixo
destination
TPRRoutingLocality
StringSim
Localidade

Identificador da localidade de destino do pedido.-Tabela abaixo

Âncora
TPRRoutingLocalityTPRLocalityTPRRoutingLocality
TPRLocality

TPRRoutingLocality
TPRLocality, tipo de dado utilizado nas integrações do TPR
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
identifierStringSim4096Identificador da localidade.Texto livre, deve se único dentro da chamada."Carrefour Vila Mariana
"countryStringSim3País do endereço.Fomato ISO 3166-1 alfa-3."BRA
"
latitudeDoubleSim
Latitude.Intervalo [-90; 90].-23.6114291longitudeDoubleSimLongitude.Intervalo [-180; 180].-46.6946795
operationStringSim
Funcionamento simplificado com uma das opções: UNRESTRICTED, BUSINESS_DAYS, MORNING, AFTERNOON.

Opções:

UNRESTRICTED  (00:00-23:59 de Dom-Sab)
BUSINESS_DAYS (08:00-17:59 de Seg-Sex)
MORNING       (08:00-11:59 de Seg-Sex)
AFTERNOON     (14:00-17:59 de Seg-Sex)
BUSINESS_DAYS
addressTRPAddressSim-Endereço da localidade.-Tabela abaixo

Âncora
TPRRoutingVehiclesTPRAdressTPRRoutingVehicles
TPRAdress

TPRRoutingVehicles
TPRAddress, tipo de dado utilizado nas integrações do TPR
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
identifierStringSim4096Identificador
do tipo do veículo;
Quando a disponibilidade for insuficiente, podemos retornar novas instâncias deste veículo marcados como viagem extra;
Sempre será escolhido para as viagens extras os veículos que minimizem o número de viagens
da localidade.Texto livre, deve se único dentro da chamada."
Truck
Carrefour Vila Mariana"

"Carreta"

weightCapacity
countryString
Double
Sim
Capacidade do veículo em quilos.

Se preenchido, deve ser maior ou igual a zero.
Validado de acordo com o campo "capacityCriteria".

25000volumeCapacityDoubleSimCapacidade do veículo em metros cúbicos.Se preenchido, deve ser maior ou igual a zero.
Validado de acordo com o campo "capacityCriteria".5000speedDoubleNãoDefine a velocidade que dos veículos em uma roteirização.

Se preenchido, deve ser maior que zero. 

Senão, utilizaremos 30 km/h.

quantityIntNãoQuantidade de veículos, semelhantes a este, disponíveis.

Zerado, nulo ou omitido para os cenários de "Frota Ideal".

Se passados valores quebrados apenas a parte inteira será considerada.

ÂncoraTRPRoutingRestrictionsTRPRoutingRestrictionsTPRRoutingRestrictions, tipo de dado utilizado nas integrações do TPRCampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplosmaxLoadingStopsIntNão

Quantidade máxima de paradas de carregamento por viagem.

Se preenchido, deve ser maior que zero;

Se passados valores quebrados apenas a parte inteira será considerada.

1maxUnloadingStopsIntNãoQuantidade máxima de paradas de descarregamento por viagem.

Se preenchido, deve ser maior que zero.

Se passados valores quebrados apenas a parte inteira será considerada.

15allowInterleavingBooleanNãoPermite carregamento após descarregamento na mesma viagem. Default: false

Tabela para validação de campos Boolean.

maxDistanceBetweenLoadStopsDoubleNãoMáxima distância, em km, entre paradas de carregamento.Se preenchido, deve ser maior que zero.100maxDistanceBetweenUnloadStopsDoubleNãoMáxima distância, em km, entre paradas de descarregamento.Se preenchido, deve ser maior que zero.100 ÂncoraTPRRoutingOptionsTPRRoutingOptionsTPRRoutingOptions, tipo de dado utilizado nas integrações do TPRCampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemploscapacityCriteriaStringSim4096Tipos de roteirização: WEIGHT, VOLUME ou BOTHOpções: WEIGHT, VOLUME ou BOTH."WEIGHT"routingInstantTypeStringNão4096Define o instante em que as viagens podem ser expedidas. Valor default D+1
"Now" considera a saída como hora do servidor no momento da roteirização + 1 hora
"D+1" Primeiro horário factível na origem de acordo com o funcionamento da mesma.Valores: "D+1", "NOW"."NOW"considerReturnDistanceBooleanNão

Verifica se é para contabilizar a distância de retorno a origem na roteirização. 

Tabela para validação de campos Bolean.

Se não informado assumiremos "False".

minServiceDurationLongNão

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

Se preenchido, não pode ser negativo, em Milissegundos.

3600000 [ms]maxServiceDurationLongNão

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

Se preenchido, não pode ser negativo, em Milissegundos.

3600000 [ms]driverRestTimesStringNãoDescanso do motoristaOpções: Default"Default"tollCalculationBooleanNãoCalculo do pedágio

Tabela para validação de campos Bolean.

Se não informado assumiremos "False".

ÂncoraTPRRoutingResponseTPRRoutingResponse

Layout de Resposta

TPRRoutingResponse, tipo de dado utilizado nas integrações do TPRCampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplosresponseDateDate TimeSimData do envio da resposta no TPR.-2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZDversionStringSim4096Versão do TPR que executou a resposta.-0.0.0.1successBooleanSimTrue se sucesso, false se falha.Se uma única validação falhar, todo o pacote falha.TruemessageTPRMessage[]SimLista de mensagens a serem exibidas pelo sistema externo para o usuário.- ÂncoraTPRMessage TPRMessage

TPRMessage: Tipo de dado utilizado nas integrações do TPR

CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplosmessageCodeStringSim4096Código de identificação da mensagem.Código existente e válido.TPR0001messageStringSim4096Mensagem escrita.Texto Livre."Para finalizar o cadastro, acesse seu e-mail e valide o Token" ÂncoraTRPFrota_IdealTRPFrota_Ideal

Frota Ideal: A roteirização com a frota ideal, ocorre quando não limitamos as quantidades disponíveis dos veículos que serão utilizados em uma determinada roteirização, definimos apenas os tipos destes, por exemplo:

Dada uma cesta de pedidos com vinte pedidos de 5.000 kg sem janela de coleta ou entrega e os veículos disponíveis são Carretas com capacidade de 25.000 kg e Trucks com capacidade de 10.000 kg: 

Se eu não limito a quantidade disponível de veículos, o sistema roteirizara quatro viagens com Carretas, e esta é a frota ideal para este cenário;

Se eu limito os veículos disponíveis em duas Carretas e vinte Trucks, o sistema roteirizara sete viagens, duas com Carretas e cinco com Trucks e esta é a melhor frota factível para este cenário, porem não é a frota ideal;

3Pais do endereço.Formato ISO 3166-1 alfa-3"BRA"
stateStringNão2Estado do endereço.Quando Brasil valida as 27 opções, se informadoSP
cityStringNão4096Cidade do endereço.Texto livreBauru
zipCodeStringNão4096CEP do endereço.Valida formato, se informado e se BRA17047-001
addressStringSim4096Rua, número, Bairro e complemento do endereço.Texto livreGomes de carvalho, 940
latitudeDoubleSim
Latitude do endereço.Intervalo [-90; 90].-23.6114291
longitudeDoubleSim
Longitude do endereço.Intervalo [-180; 180].-46.6946795
Âncoraboolean_tabboolean_tab

Tabela de Boolean:

Valor Assumido

Valor recebido

True

"true"

true12-1-2""False

false

0"false"null

Anexos

Anexos
oldfalse