Á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 JSON, 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 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 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
qualifiersObjectNão4096String chave valor.Formato Json{"Usuário": "Pedro de Alcântara", "Perfil": "Analista"}
callbackURLStringSim4096URL de Call Back.Inicio com "https://"
callbackAuthenticationTypeStringSim4096Tipos de autenticação: BASIC ou NONE.Texto Livre
callbackAuthenticationValueStringNão4096Texto de acordo com formato indicado.Texto 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ç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: 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 TPR.Formato ISO2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD
versionStringNão4096Versão do TPR que executou a resposta.Texto Livre12.36.1
qualifiersObjectNão4096String chave valorFormato JSON.{"Usuário": "Pedro de Alcântara", "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
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
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 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 e este deve determinar o sucesso do envio.

Âncora
TPRCatMsg
TPRCatMsg

Catálogo de Mensagens

Código

Mensagem

Descrição

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.
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.
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.

Anexos

Anexos