Totvs Planejamento de Rotas

Árvore de páginas

Versões comparadas

Versão antiga 30

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
border

true

false
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision

3

5
diagramNameTPR Geolocalizaçã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: JSONJSON, para maiores detalhes consulte os Exemplos.

Escopo

  • Integração assíncrona de geolocalização, compostas pela chamada e pelos callbacks, nestas, receberemos uma lista endereços e, quando possível, retornaremos em pacotes de 100 linhas a latitude e a longitude para serem armazenadas no sistema externo;
  • Por que não incluir este processo dentro da integração de roteirização?
    • Para simplificar o fluxo de roteirização, isolando as complexidades da geolocalização em um fluxo específico;
    • Para garantir que ao chamar a integração de roteirização o  o cliente não receba e seja cobrado, por uma rota com 9 de 10 dos pedidos necessários quando um deles esta  com o endereço mal formatado;
  • Por que assíncrona?
    • Alguns provedores externos limitam as chamadas em determinados período de tempo;
      • Por exemplo: O Google limita em 20 mil chamadas por minuto, o que em chamadas maiores pode gerar uma espera de alguns minutos;
    • De forma assíncrona poderemos balancear as chamadas entre os clientes, e não deixar alguém que quer geolocalizar 10 linhas esperando em uma fila de 100 mil, por exemplo;

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

  • Para clientes Protheus versão xxxxxx;
  • Para clientes Datasul versão xxxxxx;
  • Para clientes externos contratação do trial via TOTVS Store;

Âncora
TPRGeolocation
TPRGeolocation

Layout de Requisição

TPRGeolocation: Integração rest,
Assincrona
Assíncrona com a TPRGeolocationCB

Path: https://planejamentorotasqa.totvs.

.

com/v1/

trp

tpr-geolocation Método: POST

Header obrigatório: Chave = "TPR_AUTHORIZATION" e Valor = Chave gerada na integração de Criação de token

CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
dateCallDate TimeSim
Data da criação da chamada no sistema externo.Formato ISO86012021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD
systemStringNão4096Identificador do sistema que fez a chamada.Texto LivreProtheus
versionStringNão4096Versão do sistema externo.Texto Livre12.36.1
qualifiers
ObjectFormato Json{"Usuário": "Pedro de Alcântara", "Perfil": "Analista"}
StringNão4096String
chave valor
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"})

callbackURLStringSim4096URL de Call Back.Inicio com "https://" quando o tipo de autenticação for diferente de NONE
callbackAuthenticationTypeStringSim4096Tipos de autenticação:
Basic, None
BASIC ou NONE.Texto Livre
callbackAuthenticationValueStringNão4096Texto de acordo com formato indicado.Texto LivreQWxhZGRpbjpvcGVuIHNlc2FtZQ==
address
addresses

TPRAddress[]

Sim
Lista de endereços a serem geolocalizados.-

Âncora
TPRAddress
TPRAddress

TPRAddress, tipo de dado utilizado nas integrações do TPR

CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
identifierStringSim4096Identificador
unico
único do endereço.Texto livreCLI-4693
countryStringSim3Pais do endereço.
Fomato ISO
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ão4096
Cep
CEP 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

Layout de Resposta

TPRGeolocationResponse: Integração rest, sincrona
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
dateResponse
dateCallDate 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
excutou
executou a resposta.-0.0.0.1
successBooleanSim
True se sucesso, false se falha
??????
.-True
messageTPRMessage[]Sim
Campo que deve ser exibido pelo sistema externo para o
usuario
usuário.-

Âncora
TPRGeolocationCB
TPRGeolocationCB
Layout do Call Back

TPRGeolocationCallback: Integração rest, Assincrona

Path: ver campo TPRGeolocation/CallbackURL, Método: POST

CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
dateCallDate TimeSim
Data do envio da
criação da chamada no sistema externo
resposta no TPR.Formato ISO2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD
versionStringNão4096Versão do
sistema externo
TPR que executou a resposta.Texto Livre12.36.1
geolocationResult
qualifiersStringNão4096String 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"})

geolocationResultsTPRGeolocationResult[]Sim
Lista de resultados de geolocalização.-Tabela abaixo

Âncora
TPRGeolocationResult
TPRGeolocationResult

TPRGeolocationResult, tipo de dado utilizado nas integrações do TPR
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
sucess
successBooleanSim
True se sucesso, false se falha.-True
identifierStringSim4096Identificador
unico
único do endereço.Texto livreCLI-4693
latitudeDoubleNão
LatitudeIntervalo [-90; 90]-23.6114291
longitudeDoubleNão
LongitudeIntervalo [-180; 180]-46.6946795
messageTPRMessage[]Sim
Campo que deve ser exibido pelo sistema externo para o
usuario
usuário.-Tabela abaixo

Âncora
TPRMessage
TPRMessage

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

CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
messageCodeStringSim4096Código de identificação da mensagem.Código existente e validoTPR0001
messageStringSim4096Mensagem escrita.Texto Livre"Para finalizar o cadastro acesse seu e-mail e valide o Token."
Informações
titleRetorno do Call Back

Não esperamos corpo na resposta para os call backs, este, será avaliado apenas pelo HTTP status

para

e este deve determinar o sucesso do envio.

Âncora

TPRCatErros

TPRCatMsg

TPRCatErros

TPRCatMsg

Catálogo de

Erros

Mensagens

Código

Mensagem

Descrição

TPRGL001

TPRGL0000Sucesso.Retorno indicando sucesso da operação.
TPRGL0001A data da chamada é obrigatória.Retorno inválido para a validação do campo dateCall, já que se encontra nulo ou vazio.
TPRGL0002Os qualificadores não estão em um formato válido (JSON).Retorno inválido para a validação do campo qualifiers, já que está diferente do formato esperado de um objeto JSON em texto.
TPRGL0003URL da chamada de retorno é obrigatória.Retorno inválido para a validação do campo callbackURL, já que se encontra nulo ou vazio.
TPRGL0004Para utilizar autenticação, a URL de chamada de retorno deve iniciar com https://.Retorno inválido para a validação do campo callbackURL, quando não estiver utilizando o protocolo HTTPS com o tipo de autenticação diferente de NONE
TPRGL0005Tipo de autenticação da chamada de retorno é obrigatório.Retorno inválido para a validação do campo callbackAuthenticationType, já que se encontra nulo ou vazio.
TPRGL0006O tipo de autenticação de callback está inválido ('BASIC', 'NONE').Retorno inválido para a validação do campo callbackAuthenticationType, já que não é uma das opções válidas (NONE e BASIC).
TPRGL0007É necessário pelo menos um endereço para ser geolocalizado.Retorno inválido para a validação do campo addresses, já que se encontra nulo ou vazio.
TPRGL0008Identificador do endereço é obrigatório.Retorno inválido para a validação do campo identifier do objeto address, já que se encontra nulo ou vazio.
TPRGL0009O país do endereço [IDENTIFICADOR_ENDERECO] é obrigatório.Retorno inválido para a validação do campo country do objeto address, já que se encontra nulo ou vazio.
TPRGL0010O país do endereço [IDENTIFICADOR_ENDERECO] não é um país válido (Formato ISO 3166-1 alpha-3).Retorno inválido para a validação do campo country do objeto address, que não se encontra como identificador de nenhum país na ISO3166-1 alpha-3.
TPRGL0011O estado do endereço [IDENTIFICADOR_ENDERECO] não é um estado válido.Retorno inválido para a validação do campo state do objeto address, já que se não se encontra como um acrônimo válido para os Estados do Brasil.
TPRGL0012O logradouro do endereço [IDENTIFICADOR_ENDERECO] é obrigatório.Retorno inválido para a validação do campo address do objeto address, já que se encontra nulo ou vazio.
TPRGL0013Não foi possível achar a geocodificação para o endereço [IDENTIFICADOR_ENDERECO] informado.Retorno informando que não foi possível gerar a geocodificação com as informações passada como endereço.
TPRGL0014Erro interno, tente novamente e se o problema persistir contate: [EMAIL_SUPORTE].Retorno de erro ao pedir para o provedor a geocodificação com as informações passada como endereço.
TPRGL0015O valor do sistema possui mais de 4096 caracteres.Retorno inválido para a validação do campo system, porque é maior que 4096 caracteres.
TPRGL0016O valor da versão possui mais de 4096 caracteres.Retorno inválido para a validação do campo version, porque é maior que 4096 caracteres.
TPRGL0017O valor dos qualificadores possui mais de 4096 caracteres.Retorno inválido para a validação do campo qualifiers, porque é maior que 4096 caracteres.
TPRGL0018O valor da URL de callback possui mais de 4096 caracteres.Retorno inválido para a validação do campo callbackURL, porque é maior que 4096 caracteres
TPRGL0019O valor da URL de autenticação de callback possui mais de 4096 caracteres.Retorno inválido para a validação do campo callbackAuthenticationValue, porque é maior que 4096 caracteres.
TPRGL0020O valor do identificador de endereço possui mais de 4096 caracteres.Retorno inválido para a validação do campo identifier do objeto address, porque é maior que 4096 caracteres.
TPRGL0021O valor da cidade do endereço [IDENTIFICADOR_ENDERECO] possui mais de 4096 caracteres.Retorno inválido para a validação do campo city do objeto address, porque é maior que 4096 caracteres.
TPRGL0022O valor do CEP do endereço [IDENTIFICADOR_ENDERECO] possui mais de 4096 caracteres.Retorno inválido para a validação do campo zipCode do objeto address, porque é maior que 4096 caracteres.
TPRGL0023O valor do logradouro do endereço [IDENTIFICADOR_ENDERECO] possui mais de 4096 caracteres.Retorno inválido para a validação do campo address do objeto address, porque é maior que 4096 caracteres.
TPRGL0024O CEP do endereço [IDENTIFICADOR_ENDERECO] não é um cep válido.Retorno inválido para a validação do campo zipCode do objeto address, quando não respeita o padrão de 5 números, "-" e 3 números.
TPRGL0025A mensagem está mal formatada.Retorno indicando que a mensagem está diferente do contrato indicado acima, logo se encontra num formato inválido.
TPRGL0026Data da chamada mal formatada.Retorno indicando que algum campo que seja datetime está com formatação inválido.
TPRGL0027O identificador do endereço [IDENTIFICADOR_ENDERECO] deve ser único.Retorno inválido para a validação do campo identifier do objeto address, já que se encontrada repetido.
TPRGL0028Valor para autenticação da chamada de retorno é obrigatório quando o tipo de autenticação for BASIC.Retorno inválido para a validação do campo callbackAuthenticationValue, já que se encontra nulo ou vazio e o callbackAuthenticationType se encontra com o valor BASIC.
TPRTK0032A chave do token não foi informada.Retorno inválido para requisição que não envia o header "TPR_AUTHORIZATION" com a chave do token.
TPRTK0033A chave do token informada não foi encontrada.Retorno inválido para requisição que enviar uma chave no header "TPR_AUTHORIZATION" que não existe na base de dados.
TPRTK0034A vigência do seu plano chegou ao fim. Para reativar refaça o cadastro.Retorno inválido para requisição que enviar uma chave no header "TPR_AUTHORIZATION" que não tenha um plano vigente.
TPRTK0035Seu plano mensal já foi consumido.Retorno inválido para requisição que enviar uma chave no header "TPR_AUTHORIZATION" que já tenha consumido toda quota de rotas e/ou roteirizações do plano vigente.
TPRTK0036O seu período de pré-trial acabou! Você ainda pode experimentar o TOTVS PLANEJAMENTO DE ROTAS por 30 dias, gratuitamente, assinando o Trial através da TOTVS Store [Link TOTVS Store].Retorno inválido para requisição que enviar uma chave no header "TPR_AUTHORIZATION" que já tenha consumido toda quota de roteirizações ou finalizado o tempo de "TRIAL"
TPRTK0037O seu trial chegou ao fim. Para continuar usando o Totvs Planejamento de Rotas, faça a contratação acessando "https://partner.totvs.store/br/produto/totvs-planejamento-de-rotas.html".Retorno inválido para requisição que enviar uma chave no header "TPR_AUTHORIZATION" que já tenha finalizado o tempo de "TRIAL"

Anexos

Anexos