Á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
borderfalse
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision4
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: JSON

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 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 com a TPRGeolocationCB
Path: .../v1/tpr-geolocation Método: POST
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
dateCallDate TimeSim
Data da criação da chamada no sistema externoFormato ISO86012021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD
systemStringNão4096Identificador do sistema que fez a chamadaTexto LivreProtheus
versionStringNão4096Versão do sistema externoTexto Livre12.36.1
qualifiersObjectNão4096String chave valorFormato Json{"Usuário": "Pedro de Alcântara", "Perfil": "Analista"}
callbackURLStringSim4096URL de Call BackInicio com "https://"
callbackAuthenticationTypeStringSim4096Tipos de autenticação: BASIC ou NONETexto Livre
callbackAuthenticationValueStringNão4096Texto de acordo com formato indicadoTexto LivreQWxhZGRpbjpvcGVuIHNlc2FtZQ==
addressSim
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 único do endereçoTexto livreCLI-4693
countryStringSim3Pais do endereçoFormato ISO 3166-1 alfa-3"BRA"
stateStringNão2Estado do endereçoQuando Brasil valida as 27 opções, se informadoSP
cityStringNão4096Cidade do endereçoTexto livreBauru
zipCodeStringNão4096CEP do endereçoValida formato, se informado e se BRA17047-001
addressStringSim4096Rua, número, Bairro e complemento do endereçoTexto livreGomes de carvalho, 940

Layout de Resposta

TPRGeolocationResponse: 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
successBooleanSim
True se sucesso, false se falha-True
messageTPRMessage[]Sim
Campo que deve ser exibido pelo sistema externo para o 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 resposta no TPRFormato ISO2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD
versionStringNão4096Versão do TPR que executou a respostaTexto Livre12.36.1
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
successBooleanSim
True se sucesso, false se falha-True
identifierStringSim4096Identificador único do endereçoTexto 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 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 mensagemCódigo existente e validoTPR0001
messageStringSim4096Mensagem escritaTexto 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 e este deve determinar o sucesso do envio.

Âncora
TPRCatMsg
TPRCatMsg

Catálogo de Mensagens

Código

Mensagem

Descrição

TPRGL0000SucessoRetorno indicando sucesso da operação
TPRGL0001Data da criação da chamada no sistema externo é obrigatóriaRetorno inválido para a validação do campo dateCall, já que se encontra nulo ou vazio
TPRGL0002Qualifiers não estão em um formato JSON válidoRetorno 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óriaRetorno inválido para a validação do campo callbackURL, já que se encontra nulo ou vazio
TPRGL0004URL de chamada de retorno deve ser HTTPSRetorno 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órioRetorno inválido para a validação do campo callbackAuthenticationType, já que se encontra nulo ou vazio
TPRGL0006Tipo de autenticação da chamada de retorno não é válidoRetorno 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 geolocalizadoRetorno inválido para a validação do campo addresses, já que se encontra nulo ou vazio
TPRGL0008Identificador do endereço é obrigatórioRetorno inválido para a validação do campo identifier do objeto address, já que se encontra nulo ou vazio
TPRGL0009País do endereço é obrigatórioRetorno inválido para a validação do campo country do objeto address, já que se encontra nulo ou vazio
TPRGL0010País do endereço não é um país válidoRetorno 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
TPRGL0011Estado do endereço não é um estado válidoRetorno 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
TPRGL0012Logradouro do endereço é obrigatórioRetorno 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 informadoRetorno informando que não foi possível gerar a geocodificação com as informações passada como endereço
TPRGL0014Erro ao solicitar geocodificação para o provedorRetorno 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 caractereRetorno inválido para a validação do campo system, porque é maior que 4096 caracteres
TPRGL0016O valor da versão possui mais de 4096 caracteresRetorno inválido para a validação do campo version, porque é maior que 4096 caracteres
TPRGL0017O valor de qualifiers possui mais de 4096 caracteresRetorno inválido para a validação do campo qualifiers, porque é maior que 4096 caracteres
TPRGL0018O valor da URL de callback possui mais de 4096 caracteresRetorno 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 caracteresRetorno 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 caracteresRetorno inválido para a validação do campo identifier do objeto address, porque é maior que 4096 caracteres
TPRGL0021O valor da cidade de endereço possui mais de 4096 caracteresRetorno inválido para a validação do campo city do objeto address, porque é maior que 4096 caracteres
TPRGL0022O valor do CEP de endereço possui mais de 4096 caracteresRetorno inválido para a validação do campo zipCode do objeto address, porque é maior que 4096 caracteres
TPRGL0023O valor do logradouro de endereço possui mais de 4096 caracteresRetorno inválido para a validação do campo address do objeto address, porque é maior que 4096 caracteres
TPRGL0024CEP do endereço não é um cep válidoRetorno 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
TPRGL0025Formato inválidoRetorno indicando que a mensagem está diferente do contrato indicado acima, logo se encontra num formato inválido
TPRGL0026Campo de datetime enviado em formato inválidoRetorno indicando que algum campo que seja datetime está com formatação inválido
TPRGL0027O identificador do endereço deve ser únicoRetorno inválido para a validação do campo identifier do objeto address, já que se encontrada repetido

Anexos

Anexos