Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

Introdução

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision7
diagramNameTPR Roteirização
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth480

Sistemas Envolvidos

  • TPR:

    • TOTVS Planejamento de Rotas.

  • Sistema Externo:

    • Todos os ERPs que se conectam ou pretendem se conectar com os produtos de planejamento logístico TOTVS.

Integração

  • Formato de entrada/saída: JSON

Escopo

  • |Integração assíncrona de roteirização, compostas pela chamada e pelos callback, nestas, receberemos uma lista pedidos e, quando possível, retornaremos viagens para o sistema externo;

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: Integração rest, Assíncrona

Path: .../v1/    , Método: POST

CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
dateCallDate TimeSim
Data da criação da chamada no sistema externoFormato ISO8601.2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD
systemStringNão4096Identificador do sistema que fez a chamadaTexto Livre.Protheus
versionStringNão4096Versão do sistema externoTexto Livre.12.36.1
qualifiersObjectNão4096String chave valorFormato JSON.{"Usuário": "Pedro de Alcântara", "Perfil": "Analista"}
callbackURLStringSim4096URL de CallbackInício com "https://".
callbackAuthenticationTypeStringSim4096Tipos de autenticação: BASIC, NONEOpções: BASIC, NONE.NONE
callbackAuthenticationValueStringNão4096Texto de acordo com formato indicadoTexto Livre.QWxhZGRpbjpvcGVuIHNlc2FtZQ==
capacityCriteriaStringSim4096Tipos de roteirização: WEIGHT, VOLUME ou BOTHOpções: WEIGHT, VOLUME ou BOTH."WEIGHT"
ordersTPRRoutingOrders[]Sim
Lista de pedidos a serem roteirizados
Tabela abaixo
vehiclesTPRRoutingVehicles[]Sim
Lista de veículos disponíveis para a roteirização
Tabela abaixo
restrictionsTRPRoutingRestrictionsSim
Restrições de roteirização
Tabela abaixo
OptionsoptionsTPRRoutingOptionsSim
Opções de roteirização
Tabela abaixo

Âncora
TPRRoutingOrders
TPRRoutingOrders

TPRRoutingOrders, tipo de dado utilizado nas integrações do TPR
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
identifierStringSim4096Identificador do pedidoTexto livre;
Ú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, e;
Validado de acordo com o campo "capacityCriteria".

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

5000
pickupTimeWindowStartDate TimeNão
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 se ambos forem preenchidos.

"2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD"
pickupTimeWindowEndDate TimeNão
Final da janela de carregamentoFormato 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 TimeNão
Final da janela de entrega

Formato ISO8601;
DeliveryEnd deve vir posterior de PickupStart se ambos forem preenchidos.

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

DeliveryEnd deve vir posterior de DeliveryStart se ambos forem preenchidos.

"2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD"
serviceLoadDurationLongNão
Se não informado, será considerado um serviço de 30 minutosSe preenchido, deve ser maior que zero, em Milissegundos.3600000 [ms]
serviceUnloadDurationLongNão
Se não informado, será considerado um de 30 minutosSe preenchido, deve ser maior que zero, em Milissegundos.3600000 [ms]
originTPRRoutingLocalitySim
Localidade de origem do pedido-Tabela abaixo
destinationTPRRoutingLocalitySim
Localidade de destino do pedido-Tabela abaixo

Âncora
TPRRoutingLocality
TPRRoutingLocality

TPRRoutingLocality, tipo de dado utilizado nas integrações do TPR
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
identifierStringSim4096Identificador da localidadeTexto Livre."Carrefour Vila Mariana"
countryStringSim3País do endereçoFomato ISO 3166-1 alfa-3."BRA"
latitudeDoubleSim
LatitudeIntervalo [-90; 90].-23.6114291
longitudeDoubleSim
LongitudeIntervalo [-180; 180].-46.6946795
operationStringSim
Funcionamento simplificadoOpções: UNRESTRICTED, BUSINESS_DAYS, MORNING, AFTERNOON.BUSINESS_DAYS

Âncora
TPRRoutingVehicles
TPRRoutingVehicles

TPRRoutingVehicles, 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.
Texto livre.

"Truck"

"Carreta"

weightCapacityDoubleSim
Capacidade do veículo em quilos

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

25000
volumeCapacityDoubleSim
Capacidade do veículo em metros cúbicosSe preenchido, deve ser maior ou igual a zero, e;
Validado de acordo com o campo "capacityCriteria".
5000
speeddoubleNão
Define a velocidade que dos veículos em uma roteirização.

Se preenchido, deve ser maior que zero;

Se não informado trabalharemos com a menor entre as velocidades informadas e se nenhum for informado: 30 km/h.


quantityIntNão
Quantidade 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.


Âncora
TRPRoutingRestrictions
TRPRoutingRestrictions

TPRRoutingRestrictions, tipo de dado utilizado nas integrações do TPR
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
maxLoadingStopsIntNã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.

1
maxUnloadingStopsIntNão
Quantidade 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.

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

Tabela para validação de campos Bolean


maxDistanceBetweenLoadStopsDoubleNão
Máxima distância, em km, entre paradas de carregamento;Se preenchido, deve ser maior que zero.100
maxDistanceBetweenUnloadStopsDoubleNão
Máxima distância, em km, entre paradas de descarregamento;Se preenchido, deve ser maior que zero.100

Âncora
TPRRoutingOptions
TPRRoutingOptions

TPRRoutingOptions, tipo de dado utilizado nas integrações do TPR
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
routingInstantTypeStringNão4096Define o instante em que a 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 distancia de retorno a origem na roteirização. 

Tabela para validação de campos Bolean;

Se não informado assumiremos "False".


Âncora
TPRRoutingResponse
TPRRoutingResponse

Layout de Resposta

TPRRoutingResponse, tipo de dado utilizado nas integrações do TPR
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
responseDateDate TimeSim
Data do envio da resposta no TPR-2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD
versionStringSim4096Versão do TPR que executou a resposta-0.0.0.1
successBooleanSim
True se sucesso, false se falhaSe uma única validação falhar, todo o pacote falha.True
messageTPRMessage[]Sim
Lista de mensagens a serem exibidas pelo sistema externo para o usuário-

Âncora
TPRMessage
TPRMessage

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

CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
messageCodeStringSim4096Código de identificação da mensagemCódigo existente e válido.TPR0001
messageStringSim4096Mensagem escritaTexto Livre."Para finalizar o cadastro, acesse seu e-mail e valide o Token"

Âncora
TPRCatMsg
TPRCatMsg

Catálogo de Mensagens

CódigoMensagemDescrição
TPRRT0000SucessoSucesso
TPRRT0001A mensagem está nulaAo enviar um payload nulo
TPRRT0002A mensagem está vaziaAo enviar um payload vazio
TPRRT0003A data de criação está nulaAo enviar campo "dataCall" nula
TPRRT0004O valor da versão possui mais de 4096 caracteresAo enviar o campo "version" com mais de 4096 caracteres
TPRRT0005A chave dos qualificadores possui mais de 4096 caracteresAo enviar o campo "qualifiers" que possui uma chave com mais de 4096 caracteres
TPRRT0006A máxima distância de paradas de carregamento não pode ser menor que 0Ao enviar o campo "maxDistanceBetweenLoadStops" com o valor menor a 0
TPRRT0007O valor do sistema possui mais de 4096 caracteresAo enviar o campo "system" com mais de 4096 caracteres
TPRRT0008A url de callback está nulaAo enviar o campo "callbackUrl" nula
TPRRT0009A url de callback está inválidaAo enviar o campo "callbackUrl" inválida
TPRRT0010O valor da url de callback possui mais de 4096 caracteresAo enviar o campo "callbackUrl" com mais de 4096 caracteres
TPRRT0011O tipo de autenticação de callback está nulaAo enviar o campo "callbackAuthenticationType" nulo
TPRRT0012O valor do tipo de autenticação de callback possui mais de 4096 caracteresAo enviar o campo "callbackAuthenticationType" com mais de 4096 caracteres
TPRRT0013O tipo de autenticação de callback está inválido ('BASIC', 'NONE')Ao enviar o campo "callbackAuthenticationType" inválido
TPRRT0014O tipo de roteirização está nuloAo enviar o campo "capacityCriteria" nula
TPRRT0015O valor do tipo de roteirização possui mais de 4096 caracteresAo enviar o campo "capacityCriteria" com mais de 4096 caracteres
TPRRT0016O tipo de roteirização está inválido ('WEIGHT', 'VOLUME', 'BOTH')Ao enviar o campo "capacityCriteria" com valores diferentes de ('WEGHT', 'VOLUME', 'BOTH')
TPRRT0017O valor do instante da roteirização possui mais de 4096 caracteresAo enviar o campo "routingInstantType" com mais de 4096 caracteres
TPRRT0018A restrição está nulaAo enviar o campo "restriction" nula
TPRRT0019A localidade está nulaAo enviar alguma localidade nula
TPRRT0020O identificador da localidade está inválidoAo enviar o Identificador da Localidade vazio ou nulo
TPRRT0021A latitude da localidade [IDENTIFICADOR_LOCALIDADE] está nulaAo enviar a latitude de alguma localidade nula
TPRRT0022A longitude da localidade [IDENTIFICADOR_LOCALIDADE] está nulaAo enviar a longitude de alguma localidade nula
TPRRT0023A operação da localidade [IDENTIFICADOR_LOCALIDADE] está nulaAo enviar o funcionamento de alguma localidade nula
TPRRT0024O país da localidade [IDENTIFICADOR_LOCALIDADE] está nulaAo enviar o campo "country" de alguma localidade nulo
TPRRT0025O valor do identificador da localidade possui mais de 4096 caracteresAo enviar o campo "identifier" de alguma localidade com mais de 4096 caracteres
TPRRT0026O país da localidade [IDENTIFICADOR_LOCALIDADE] está inválido. O mesmo deve seguir o formato ISO 3166-1 alfa-3Ao enviar o campo "country" com mais de 3 caracteres
TPRRT0027O país da localidade [IDENTIFICADOR_LOCALIDADE] não foi encontradoAo enviar o campo "country" que não está informado no TPRCountry
TPRRT0028A latitude da localidade [IDENTIFICADOR_LOCALIDADE] está inválido a mesma precisa estar dentro do intervalo [-90; 90]Ao enviar o campo "latitude" não seguindo o padrão [-90; 90]
TPRRT0029A longitude da localidade [IDENTIFICADOR_LOCALIDADE] está inválido a mesma precisa estar dentro do intervalo [-180; 180]Ao enviar o campo "longitude" não seguindo o padrão [-180; 180]
TPRRT0030O pedido está nuloAo enviar algum pedido nulo
TPRRT0031Os pedidos são inválidosAo enviar o campo pedido vazio
TPRRT0032O identificador do pedido é obrigatórioAo enviar o identificador do pedido vazio ou nulo
TPRRT0033O peso do pedido com identificador [IDENTIFICADOR_PEDIDO] é obrigatórioAo enviar o peso do pedido nulo, caso o campo "capacityCriteria" do input seja "WEIGHT" ou "BOTH"
TPRRT0034O peso do pedido com identificador [IDENTIFICADOR_PEDIDO] deve ser maior que 0Ao enviar o peso do pedido que seja menor que 0, caso o campo "capacityCriteria" do input seja "WEIGHT" ou "BOTH"
TPRRT0035O volume do pedido com identificador [IDENTIFICADOR_PEDIDO] é obrigatórioAo enviar o campo "volume" menor que 0, caso o campo "capacityCriteria" do input seja "VOLUME" ou 'BOTH"
TPRRT0036O volume do pedido com identificador [IDENTIFICADOR_PEDIDO] deve ser maior que 0Ao enviar o campo "volume" menor que 0. caso o campo "capacityCriteria" do input seja "VOLUME"
TPRRT0037A localidade de origem do pedido [IDENTIFICADOR_PEDIDO] está nuloAo enviar a localidade de origem do pedido nula
TPRRT0038A localidade de destino do pedido [IDENTIFICADOR_PEDIDO] está nuloAo enviar a localidade de destino do pedido nula
TPRRT0039O identificador do pedido possui mais de 4096 caracteresO campo "identifier" do pedido com mais de 4096
TPRRT0040A duração de serviço de carregamento do pedido [IDENTIFICADOR_PEDIDO] não pode ser menor ou igual a 0Ao enviar o campo "serviceLoadDuration" menor que 0
TPRRT0041A duração de serviço de descarregamento pedido [IDENTIFICADOR_PEDIDO] não pode ser menor ou igual a 0Ao enviar o campo "serviceUnloadDuration" menor que 0
TPRRT0042Os veículos não podem ser nulosAo enviar o campo "vehicles" nulo
TPRRT0043Os veículos não podem ser vaziosAo enviar o campo "vehicles" vazio
TPRRT0044O identificador do veículo está inválidoAo enviar o campo "identifier" do veículo nulo ou vazio
TPRRT0045A capacidade de volume do veículo com identificador [IDENTIFICADOR_VEICULO] é obrigatórioAo enviar o campo "volumeCapacity" do veículo nula, quando o capacityCriteria é igual a VOLUME ou BOTH
TPRRT0046A capacidade de volume do veículo com identificador [IDENTIFICADOR_VEICULO] deve ser maior que 0Ao enviar o campo "volumeCapacity" do veículo é menor que 0, quando o capacityCriteria é igual a VOLUME ou BOTH
TPRRT0047A capacidade de peso do veículo com identificador [IDENTIFICADOR_VEICULO] é obrigatórioAo enviar o campo "weightCapacity" do veículo nula, quando o capacityCriteria é igual a WEIGHT ou BOTH
TPRRT0048A capacidade de peso do veículo com identificador [IDENTIFICADOR_VEICULO] deve ser maior que 0Ao enviar o campo "weightCapacity" do veículo é menor que 0, quando o capacityCriteria é igual a WEIGHT ou BOTH
TPRRT0049O identificador do veículo possui mais de 4096 caracteresAo enviar o identificador de veículo com mais de 4096 caracteres
TPRRT0050A quantidade de veículos do veículo com identificador [IDENTIFICADOR_VEICULO], se informada, deve ser maior que 0Ao enviar o campo "quantity" menor que 0
TPRRT0051O identificador do pedido [IDENTIFICADOR_PEDIDO] está duplicadoAo enviar dois pedidos com o mesmo identifier
TPRRT0052As localidades de origem e destino são iguais no pedido [IDENTIFICADOR_PEDIDO]Ao enviar uma localidade de origem e de destino com o mesmo identifier
TPRRT0053O identificador da localidade [IDENTIFICADOR_LOCALIDADE] está duplicado em outras localidadesAo enviar duas localidades quaisquer com o mesmo identifier
TPRRT0054O identificador do veículo [IDENTIFICADOR_VEICULO] está duplicado com outros veículosAo enviar veículos com identificadores iguais, mas atributos diferentes
TPRRT0055O valor dos qualificadores possui mais de 4096 caracteresAo enviar o campo "qualifiers" que possui um valor com mais de 4096 caracteres
TPRRT0056O máximo número de paradas de carregamento não pode ser menor ou igual a 0Ao enviar o campo "maxLoadingStops" com o valor menor ou igual a 0
TPRRT0057O máximo número de paradas de descarregamento não pode ser menor ou igual a 0Ao enviar o campo "maxUnloadingStops" com o valor menor ou igual a 0
TPRRT0058A máxima distância de paradas de descarregamento não pode ser menor que 0Ao enviar o campo "maxDistanceBetweenUnloadStops" com o valor menor a 0
TPRRT0059O pedido [IDENTIFICADOR_PEDIDO] possui início da janela de carregamento maior ou igual que o final da janela de carregamentoAo enviar o campo "pickupTimeWindowStart" maior ou igual que o campo "pickupTimeWindowEnd"
TPRRT0060O pedido [IDENTIFICADOR_PEDIDO] possui início da janela de descarregamento maior ou igual que o final da janela de descarregamentoAo enviar o campo "deliveryTimeWindowStart" maior ou igual que o campo "deliveryTimeWindowEnd"
TPRRT0061O pedido [IDENTIFICADOR_PEDIDO] possui início da janela de carregamento maior que o início da janela de descarregamentoAo enviar o campo "pickupTimeWindowStart" maior que o campo "deliveryTimeWindowStart"
TPRRT0062O pedido [IDENTIFICADOR_PEDIDO] possui início da janela de carregamento maior ou igual que o final da janela de descarregamentoAo enviar o campo "pickupTimeWindowStart" maior ou igual que o campo "deliveryTimeWindowEnd"
TPRRT0063O pedido [IDENTIFICADOR_PEDIDO] possui final da janela de carregamento maior que o final da janela de descarregamentoAo enviar o campo "pickupTimeWindowEnd" maior ou igual que o campo "deliveryTimeWindowStart"
TPRRT0064O peso do veículo [IDENTIFICADOR_VEÍCULO] ultrapassou o máximo permitido. Peso constatado [PESO_CONSTATADO] Peso máximo [PESO_MAXIMO]Quando o peso máximo do veículo ultrapassa o peso permitido pelo validador MaxWeightVehicleServiceLegValidator
TPRRT0065O volume do veículo [IDENTIFICADOR_VEÍCULO] ultrapassou o máximo permitido. Volume constatado [VOLUME_CONSTATADO]. Volume máximo [VOLUME_MAXIMO]Quando o volume máximo do veículo ultrapassa o volume permitido no validador MaxVolumeVehicleServiceLegValidator
TPRRT0066Não foi possível satisfazer a janela temporal dos pedidos [IDENTIFICADORES_PEDIDOS].Quando a janela de tempo dos pedidos estão infactiveis baseado no validador TimeWindowValidator
TPRRT0067Não foi possível gerar configuração temporal para a viagem [IDENTIFICADORES_VIAGENS].Quando a janela de tempo dos pedidos estão infactiveis baseado no validador PlanTimeConfigurationValidatorWrapper
TPRRT0068Viagem supera a quantidade máxima de cargas permitidas. Cargas [QUANTIDADE_CARGA], Máx [MAX_QUANTIDADE_PERMITIDA].Quando a quantidade de cargas de um protótipo de viagem for maior que 1.
TPRRT0069A velocidade deve ser maior que 0.Ao enviar o campo "speed" com o valor menor que ou igual a 0.
TPRRT0070Erro Interno, tente novamente e se o problema persistir contate o suporte.Erro caso ocorra alguma falha na roterização.



Âncora
TRPFrota_Ideal
TRPFrota_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 Truckso 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;

Âncora
boolean_tab
boolean_tab

Tabela de Boolean:

Valor Assumido

Valor recebido

True

"true"

true12-1-2""
False

false

0"false"null


Anexos

Anexos
oldfalse