Á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"
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"
ordersTPRRoutingOrders[]Sim
Lista de pedidos a serem roteirizados
Tabela abaixo
vehiclesTPRRoutingVehicles[]Sim
Lista de veículos disponíveis para a roteirização
Tabela abaixo
restrictionsTRPRoutingRestrictions[]Sim
Restriçõ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 carregamentoFormato ISO8601
PickupStart deve ser anterior a PickupEnd, 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
PickupEnd deve ser posterior de PickupStart, se ambos forem preenchidos.
"2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD"
deliveryTimeWindowStartDate TimeNão
Início da janela de entregaFormato ISO8601."2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD"
deliveryTimeWindowEndDate TimeNão
Final da janela de entregaFormato ISO8601
DeliveryEnd deve vir posterior de DeliveryStart.
"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
quantityIntNão
Quantidade de veículos, semelhantes a este, disponíveisSe preenchido, deve ser maior ou igual a zero;
Omitido para os cenários de "Frota Ideal".

Â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:

true    = true
1      = true
2      = true
-1 = true
-2      = true
""      = true
"true"  = true
false = false
0       = false
"false" = false
null    = false

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
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
TPRRT0000Sucesso

Sucesso

TPRRT0001O input é nuloAo enviar um payload nula
TPRRT0002O input é vazioAo enviar um payload vazio
TPRRT0003Data de criação está nulaAo enviar campo "dataCall" nula
TPRRT0004A versão [VERSÃO_ENVIADA] possui mais de 4096 caracteresAo enviar o campo "version" com mais de 4096 caracteres
TPRRT0005A chave [CHAVE_ENVIADA] do qualificador possui mais de 4096 caracteresAo enviar o campo "qualifiers" que possui uma chave com mais de 4096 caracteres
TPRRT0006O identificador do sistema externo [IDENTIFICADOR_EXTERNO_ENVIADO] possui mais de 4096 caracteresAo enviar o campo "system" com mais de 4096 caracteres
TPRRT0007A url de callback está nulaAo enviar o campo "callbackUrl" nula
TPRRT0008A url de callback está inválidaAo enviar o campo "callbackUrl" inválida
TPRRT0009O tipo da callback [URL_CALLBACK] possui mais de 4096 caracteresAo enviar o campo "callbackUrl" com mais de 4096 caracteres
TPRRT0010O tipo da callback está nulaAo enviar o campo "callbackAuthenticationType" nulo
TPRRT0011O valor da callback [TIPO_CALLBACK_ENVIADO] possui mais de 4096 caracteresAo enviar o campo "callbackAuthenticationType" com mais de 4096 caracteres
TPRRT0012O tipo da callback [TIPO_CALLBACK_ENVIADO] está inválido. Os valores esperados são 'BASIC' e 'NONE'"Ao enviar o campo "callbackAuthenticationType" inválido
TPRRT0013O valor da callback [TIPO_CALLBACK_ENVIADO] possui mais de 4096 caracteresAo enviar o campo "callbackAuthenticationType" com mais de 4096 caracteres
TPRRT0014A url de callback está nulaAo enviar o campo "capacityCriteria" nula
TPRRT0015O tipo de roteirização [TIPO_ROTEIRIZÇÃOROTEIRIZAÇÃO] possui mais de 4096 caracteresAo enviar o campo "capacityCriteria" com mais de 4096 caracteres
TPRRT0016O tipo de roteirização [TIPO_ROTEIRIZAÇÃO_ENVIADO] está inválido. Os valores possíveis são 'WEGHT', 'VOLUME' e 'BOTH'Ao enviar o campo "capacityCriteria" com valores diferentes de WEIGHT, VOLUME E BOTH
TPRRT0017O instante de expedição [INSTANTE_ROTEIRIZAÇÃO_ENVIADO] 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 está nulaAo enviar a latitude da localidade nula
TPRRT0022A longitude da localidade está nulaAo enviar a longitude da localidade nula
TPRRT0023A operação da localidade está nulaAo enviar o funcionamento da localidade nula
TPRRT0024País da localidade com o identificador [IDENTIFICADOR_LOCALIDADE] está nuloAo enviar o campo "country" da localidade nulo
TPRRT0025O identificador da localidade [IDENTIFICADOR_LOCALIDADE] possui mais de 4096 caracteresAo enviar o campo "identifier" da localidade com mais de 4096 caracteres
TPRRT0026O país [PAIS_ENVIADO] 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 [PAIS_ENVIADO] não está cadastradoAo enviar o campo "country" que não está informado no TPRCountry
TPRRT0028Latitude [LATITUDE_ENVIADO] 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]
TPRRT0029Longitude [LONGITUDE_ENVIADO] 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]
TPRRT0030Quantidade de veículos deve ser maior que 0Ao enviar a quantidade de veículos menor que 0
TPRRT0031O pedido está nuloAo enviar algum pedido nulo
TPRRT0032Pedidos inválidosAo enviar o campo pedido vazio
TPRRT0033O identificador do pedido é obrigatórioAo enviar o identificador do pedido vazio ou nulo
TPRRT0034O peso do pedido com identificador [PESO_ENVIADO] é obrigatórioAo enviar o peso do pedido nulo, caso o campo "capacityCriteria" do input seja "WEIGHT" ou "BOTH"
TPRRT0035O peso do pedido com identificador [PESO_ENVIADO] 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"
TPRRT0036O volume do pedido com identificador [VOLUME_ENVIADO] é obrigatórioAo enviar o campo "volume" menor que 0, caso o campo "capacityCriteria" do input seja "VOLUME" ou 'BOTH"
TPRRT0037O volume do pedido com identificador [VOLUME_ENVIADO] deve ser maior que 0"Ao enviar o campo "volume" menor que 0. caso o campo "capacityCriteria" do input seja "VOLUME"
TPRRT0038A localidade de origem do pedido [IDENTIFICADOR_PEDIDO] está nuloAo enviar a localidade de origem do pedido nula
TPRRT0039A localidade de destino do pedido [IDENTIFICADOR_PEDIDO] está nuloAo enviar a localidade de destino do pedido nula
TPRRT0040O identificador do pedido [IDENTIFICADOR_PEDIDO] possuí mais de 4096 caracteresO campo "identifier" do pedido com mais de 4096
TPRRT0041Duração de serviço de carregamento não pode ser menor ou igual a 0Ao enviar o campo "serviceLoadDuration" menor que 0
TPRRT0042Duração de serviço de descarregamento não pode ser menor ou igual a 0Ao enviar o campo "serviceUnloadDuration" menor que 0
TPRRT0043O veículo está nuloAo enviar o campo "vehicles" nulo
TPRRT0044Veículos inválidosAo enviar o campo "vehicles" vazio
TPRRT0045O identificador do veículo está inválidoAo enviar o campo "identifier" do veículo nulo ou vazio
TPRRT0046A capacidade de volume do veículo com identificador [IDENTIFICADOR_ENVIADO] é obrigatórioAo enviar o campo "volumeCapacity" do veículo nula, quando o capacityCriteria é igual a VOLUME ou BOTH
TPRRT0047A capacidade de volume do veículo com identificador [VOLUME_ENVIADO] deve ser maior que 0Ao enviar o campo "volumeCapacity" do veículo é menor que 0, quando o capacityCriteria é igual a VOLUME ou BOTH
TPRRT0048A capacidade de peso do veículo com identificador [WEIGHT_ENVIADO] é obrigatórioAo enviar o campo "weightCapacity" do veículo nula, quando o capacityCriteria é igual a WEIGHT ou BOTH
TPRRT0049A capacidade de peso do veículo com identificador  [WEIGHT_ENVIADO] deve ser maior que 0Ao enviar o campo "weightCapacity" do veículo é menor que 0, quando o capacityCriteria é igual a WEIGHT ou BOTH
TPRRT0050O identificador do veículo [IDENTIFICADOR_ENVIADO] possuí mais de 4096 caracteresAo enviar o identificador de veículo com mais de 4096 caracteres
TPRRT0051A quantidade de veículos se informada deve ser maior que 0Ao enviar o campo "quantity" menor que 0
TPRRT0052O identificador do pedido [IDENTIFICADOR_ENVIADO] está duplicadoAo enviar dois pedidos com o mesmo identifier
TPRRT0053A localidade de origem e destino são iguais"Ao enviar uma localidade de origem e de destino com o mesmo identifier
TPRRT0054O identificador da localidade  [IDENTIFICADOR_ENVIADO] está duplicado em outras localidadesAo enviar duas localidades quaisquer com o mesmo identifier
TPRRT0055O identificador do veículo [IDENTIFICADOR_ENVIADO] está duplicado em outros veículoAo enviar veículos com identificadores iguais, mas atributos diferentes
TPRRT0056A chave [CHAVE_ENVIADA] do qualificador possui mais de 4096 caracteresAo enviar o campo "qualifiers" que possui um valor com mais de 4096 caracteres
TPRRT0057O máximo número de paradas de carregamento [PARADAS_CARREGAMENTO_ENVIADA] não pode ser menor ou igual a 0Ao enviar o campo "maxLoadingStops" com o valor menor ou igual a 0
TPRRT0058O máximo número de paradas de descarregamento [PARADAS_DESCARREGAMENTO_ENVIADA] não pode ser menor ou igual a 0Ao enviar o campo "maxUnloadingStops" com o valor menor ou igual a 0
TPRRT0059A máxima distância de paradas de carregamento [DISTANCIA_CARREGAMENTO_ENVIADA] não pode ser menor que 0Ao enviar o campo "maxDistanceBetweenLoadStops" com o valor menor a 0
TPRRT0060A máxima distância de paradas de carregamento [DISTANCIA_DESCARREGAMENTO_ENVIADA] não pode ser menor que 0Ao enviar o campo "maxDistanceBetweenUnloadStops" com o valor menor a 0
TPRRT0061O pedido [IDENTIFICADOR_ENVIADO] possuí início da janela de carregamento maior que o final da janela de carregamentoAo enviar o campo "pickupTimeWindowStart" maior que o campo "pickupTimeWindowEnd"
TPRRT0062O pedido [IDENTIFICADOR_ENVIADO] possuí início da janela de descarregamento maior que o final da janela de descarregamentoAo enviar o campo "deliveryTimeWindowStart" maior que o campo "deliveryTimeWindowEnd"

Documentações relacionadas

Â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;

Anexos

Anexos
oldfalse