Callback da roteirização - ERPs

Introdução

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 JSON, para maiores detalhes consulte os Exemplos.

Escopo

Integração assíncrona de roteirização, compostas pela chamada e pelos callback, nestas, receberemos uma lista pedidos e, quando possível, retornaremos rotas 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 do Callback

TPRRoutingCallback: Integração rest, Assincrona Path: ver campo TPRrouting/CallbackURL, Método: POST
Campo	Tipo	Obrigatório	Tamanho	Descrição	Validações	Exemplos
responseDate	Date Time	Sim		Data do envio da resposta no TPR	Formato ISO8601	2021-01-21T10:01:00.0-03:00 YYYY-MM-DDThh:mm:ss.sTZD
version	String	Não	4096	Versão do TPR que executou a resposta	Texto Livre	12.36.1
qualifiers	String	Não	4096	String representando um objeto JSON que tenha o nome da variável e valor sendo String.	Formato JSON.	"{ \"Usuario\": \"Pedro\", \"Perfil\": \"Analista\" }" OBS: É equivalente usar: JSON.stringify( {"Usuario":"Pedro", "Perfil":"Analista"})
summary	TPRSummary	Sim
tripsResults	TPRTrip[]	Sim		Lista de rotas geradas via otimização		Tabela abaixo
rejections	TPRRejection[]	Não		Lista de rejeites geradas via otimização		Tabela abaixo
message	TPRMessage[]	Não		Campo que deve ser exibido pelo sistema externo para o usuário	-	Tabela abaixo

TPRSummary, tipo de dado utilizado nas integrações do TPR
Campo	Tipo	Obrigatório	Tamanho	Descrição	Validações	Exemplos
totalDistance	double	Sim		Distância total do plano de rotas, em km	Maior ou igual a zero	3022 [km]
totalTrips	integer	Sim		Quantidade total de rotas do plano	Maior ou igual a zero	43 [Rotas]
totalStops	integer	Sim		Quantidade total de paradas do plano de rotas	Maior ou igual a zero	239 [Paradas]
totalVolume	double	Sim		Volume total em rotas, em m³	Maior ou igual a zero	50.000 [m³]
totalWeight	double	Sim		Peso total em rotas, em kg	Maior ou igual a zero	2.500.000 [kg]
totalDuration	double	Sim		Duração total do plano de rotas, em milissegundos	Maior ou igual a zero	57600000 [ms]
rejectedOrders	integer	Sim		Quantidade de pedidos rejeitados	Maior ou igual a zero	10 [Pedidos]
rejectedWeight	double	Sim		Total de peso rejeitado, em kg	Maior ou igual a zero	2.500.000 [kg]
rejectedVolume	double	Sim		Total de volume rejeitado, em m³	Maior ou igual a zero	50.000 [m³]

TPRTrip, tipo de dado utilizado nas integrações do TPR
Campo	Tipo	Obrigatório	Tamanho	Descrição	Validações	Exemplos
sequential	integer	Sim		Sequencial representando um número para a rota		1
distance	double	Sim		Distancia total planejada para a rota em km		123 [km]
tollValue	double	Não		Valor do pedágio	Depende do campo tollCalculation	120,32 [R$]
numberOfStops	integer	Sim		Quantidade total de paradas (carregamentos e descarregamentos) da rota
volume	double	Sim		Volume total na rota, em m³		14.32 [m³]
weight	double	Sim		Peso total na rota, em kg		12000 [kg]
duration	double	Sim		Duração total planejada para a rota em horas, minutos e segundos	Maior que zero em Millesegundos	3600000 [ms]
extraTrip	Boolean	Sim		True se o veiculo disponível, false se não disponível;
considerReturnDistance	Boolean	Não		Informa se o retorno a origem na roteirização foi considerada.	Tabela para validação de campos Boolean.
vehicle	TPRRoutingVehicles	Sim		Veículo selecionado da rota
stops	TPRTripStop[]	Sim		Lista de paradas		Tabela abaixo

TPRRoutingVehicles, tipo de dado utilizado nas integrações do TPR
Campo	Tipo	Obrigatório	Tamanho	Descrição	Validações	Exemplos
identifier	String	Sim	4096	Identificador do tipo do veículo; Quando a disponibilidade for insuficiente, podemos retornar novas instâncias deste veículo marcados como rota extra; Sempre será escolhido para as rotas extras os veículos que minimizem o número de rotas.	Texto livre, deve se único dentro da chamada.	"Truck" "Carreta"
weightCapacity	Double	Sim		Capacidade do veículo em quilos.	Se preenchido, deve ser maior ou igual a zero. Validado de acordo com o campo "capacityCriteria".	25000
volumeCapacity	Double	Sim		Capacidade do veículo em metros cúbicos.	Se preenchido, deve ser maior ou igual a zero. Validado de acordo com o campo "capacityCriteria".	5000
quantity	Integer	Nã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.
speed	Double	Não		Define a velocidade que dos veículos em uma roteirização.	Se preenchido, deve ser maior que zero. Senão, utilizaremos 30 km/h.
vehicleType	TPRVehicleType	Não		TRUCK \| CAR \| MOTORCYCLE	Se não preenchido será considerado TRUCK. É utilizado no calculo do pedágio e para restrições de trafego de caminhões.
tollAxes	Integer	Não		Quantidade de eixos durante a rota.	Se informado será considerado no calculo do pedágio.	6
tollReturnAxes	Integer	Não		Quantidade de eixos durante o retorno para a origem.	Se informado será considerado no calculo do pedágio.	4

TPRTripStop, tipo de dado utilizado nas integrações do TPR
Campo	Tipo	Obrigatório	Tamanho	Descrição	Validações	Exemplos
sequence	integer	Sim		Ordem da parada, iniciando por 1		1, 2 ... 99
type	String	Sim		LOAD: Para apenas de carregamento UNLOAD: Parada apenas de descarregamento BOTH: Parada de carregamento e descarregamento	-
distance	double	Sim		Distância em km da para anterior para a atual	Maior ou igual a zero	202 [km]
tollValues	TPRTollValue[]	Não		Lista dos valores dos pedágios da parada anterior para a atual, discriminado pelo nome da praça de pedágio	Depende do campo tollCalculation	Tabela abaixo
locality	TPRRoutingLocality	Sim		Identificador da localidade	Texto Livre	"Carrefour vila Mariana"
arrivalTime	DateTime	Sim		Horário de chegada	Formato ISO	2021-01-21T10:01:00.0-03:00 YYYY-MM-DDThh:mm:ss.sTZD
departureTime	DateTime	Sim		Horário de saída	Formato ISO	2021-01-21T10:01:00.0-03:00 YYYY-MM-DDThh:mm:ss.sTZD
loadedOrders	TPRRoutedOrder[]	Sim		Lista de pedidos carregados naquela parada		Tabela abaixo
unloadedOrders	TPRRoutedOrder[]	Sim		Lista de pedidos descarreagados naquela parada		Tabela abaixo

TPRTripStop, tipo de dado utilizado nas integrações do TPR
Campo	Tipo	Obrigatório	Tamanho	Descrição	Validações	Exemplos
name	String	Sim		Nome da praça de pedágio.		SPMAR
value	Double	Sim		Valor do pedágio		3.9

TPRRoutingLocality, tipo de dado utilizado nas integrações do TPR
Campo	Tipo	Obrigatório	Tamanho	Descrição	Validações	Exemplos
identifier	String	Sim	4096	Identificador da localidade	Texto Livre	"Carrefour 123-1"
name	String	Não	4096	Nome da localidade	Texto Livre	"Carrefour Vila Mariana"
country	String	Sim	3	País do endereço	Formato ISO 3166-1 alfa-3	"BRA"
latitude	Double	Sim		Latitude	Intervalo [-90; 90]	-23.6114291
longitude	Double	Sim		Longitude	Intervalo [-180; 180]	-46.6946795
operation	String	Sim		Funcionamento simplificado	Opções: UNRESTRICTED, BUSINESS_DAYS, MORNING, AFTERNOON	BUSINESS_DAYS

TPRRejection, tipo de dado utilizado nas integrações do TPR
Campo	Tipo	Obrigatório	Tamanho	Descrição	Validações	Exemplos
messages	TPRMessage[]	Sim	4096	Lista de mensagens de rejeito do pedido		Tabela abaixo
order	TRPRoutedOrder	Sim		Pedido rejeitado		Tabela abaixo

TPRRoutedOrder, tipo de dado utilizado nas integrações do TPR
Campo	Tipo	Obrigatório	Tamanho	Descrição	Validações	Exemplos
identifier	String	Sim	4096	Identificador do pedido	Texto livre	"Entrega Carrefour" "PED00133"
weight	Double	Não		Peso total os itens do pedido, em kg	Se não tiver peso tem que ter volume; Todos os pedidos da roteirização devem ter o mesmo limitador (Peso ou Volume);	25.000
volume	Double	Não		Volume total dos itens do pedido em m³	Se não tiver volume tem que ter peso; Todos os pedidos da roteirização devem ter o mesmo limitador (Peso ou Volume);	5000

TPRMessage: Tipo de dado utilizado nas integrações do TPR
Campo	Tipo	Obrigatório	Tamanho	Descrição	Validações	Exemplos
messageCode	String	Sim	4096	Código de identificação da mensagem	Código existente e valido	TPR0001
message	String	Sim	4096	Mensagem escrita	Texto Livre	"Para finalizar o cadastro acesse seu e-mail e valide o Token"

Retorno do Call Back

Não esperamos corpo na resposta para os callbacks, este, será avaliado apenas pelo HTTP status e este deve determinar o sucesso do envio.

	Arquivo	Modificado

Ainda não há arquivos compartilhados aqui.

Árvore de páginas