Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.
Aviso
titleIMPORTANTE
  • 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_Geoloc_Sinc
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth348

Sistemas Envolvidos

  • TPR: TOTVS Planejamento de Rotas.
  • Sistema Externo: Todos os ERPs ERP's 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 síncrona de geolocalização;
  • 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 cliente não receba e seja cobrado, por uma rota com 9 de 10 dos pedidos necessários quando um deles esta  está com o endereço mal formatado;

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-sinc
RestTPRSyncGeolocation: Integração rest, Sincrona

Path: https://planejamentorotasqa.totvs.

.

com/v1/tpr-geolocation-

sinc 

sync 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
Object
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

Formato Json{"Usuário

":"Pedro

de Alcântara

", "Perfil":"Analista"})

address
Cópia de Integração de Geolocalização [Não usar]
Sim
Endereço a ser geolocalizado.-

Âncora
TPRAddress
TPRAddress

TPRAddress

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

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

Layout de Resposta

TPRGeolocationResponse
RestTPRSyncGeolocationResponse: Integração rest, sincrona
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
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 executou a resposta.-0.0.0.1
geolocationResult
Cópia de Integração de Geolocalização [Não usar]
RestTPRGeolocationResultSim
Resultado de geolocalização.-Tabela abaixo

Âncora
TPRGeolocationResult
TPRGeolocationResult

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

Âncora
TPRMessage
TPRMessage

TPRMessage

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

Âncora
TPRCatMsg
TPRCatMsg

Catálogo de Mensagens

Código

Mensagem

Descrição

TPRGL0000TPRGL0002
TPRGS0000Sucesso.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.
TPRGS0001
Os 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.TPRGL0004A 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.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 o 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.
TPRGS0002O valor
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 caracteresTPRGL0019O 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
TPRGS0003

A geolocalização foi interrompida por exceder o tempo limite de espera.

Retorno indicando que ocorreu um timeout na geolocalização, não sendo possível gerar uma latitude e longitude para o endereço. Sendo assim, deve-se tentar enviar a request novamente.
Informações

Todas as mensagens previstas na integração de geolocalização assíncrona também podem ser retornadas.

Anexos

Anexos