Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.
Comentário: Adiciona catalogo de mensagens de geolocation

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/trp-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, 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álido.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
TPRGL0004URL da chamada de retorno não está num formato válidoRetorno inválido para a validação do campo callbackURLcampo callbackURL, já que está em um formato válido para uma URL
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 

Anexos

Anexos