Histórico da Página
Introdução
draw.io Diagram border false viewerToolbar true fitWindow false diagramDisplayName lbox true revision 4 diagramName TPR Geolocalização simpleViewer false width links auto tbstyle hidden diagramWidth 480
| border | false |
|---|---|
| viewerToolbar | true |
| fitWindow | false |
| diagramDisplayName | |
| lbox | true |
| revision | 4 |
| diagramName | TPR Geolocalização |
| simpleViewer | false |
| width | |
| links | auto |
| tbstyle | hidden |
| diagramWidth | 480 |
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;
- Alguns provedores externos limitam as chamadas em determinados período de tempo;
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
| TPRGeolocation | |
| TPRGeolocation |
Layout de Requisição
| TPRGeolocation: Integração rest, Assincrona com a TPRGeolocationCB | ||||||
| Path: .../v1/tpr-geolocation Método: POST | ||||||
| Campo | Tipo | Obrigatório | Tamanho | Descrição | Validações | Exemplos |
| dateCall | Date Time | Sim | Data da criação da chamada no sistema externo | Formato ISO8601 | 2021-01-21T10:01:00.0-03:00 YYYY-MM-DDThh:mm:ss.sTZD | |
| system | String | Não | 4096 | Identificador do sistema que fez a chamada | Texto Livre | Protheus |
| version | String | Não | 4096 | Versão do sistema externo | Texto Livre | 12.36.1 |
| qualifiers | Object | Não | 4096 | String chave valor | Formato Json | {"Usuário": "Pedro de Alcântara", "Perfil": "Analista"} |
| callbackURL | String | Sim | 4096 | URL de Call Back | Inicio com "https://" | |
| callbackAuthenticationType | String | Sim | 4096 | Tipos de autenticação: BASIC ou NONE | Texto Livre | |
| callbackAuthenticationValue | String | Não | 4096 | Texto de acordo com formato indicado | Texto Livre | QWxhZGRpbjpvcGVuIHNlc2FtZQ== |
| address | Sim | Lista de endereços a serem geolocalizados | - | |||
| Âncora | ||||
|---|---|---|---|---|
|
TPRAddress, tipo de dado utilizado nas integrações do TPR | ||||||
| Campo | Tipo | Obrigatório | Tamanho | Descrição | Validações | Exemplos |
| identifier | String | Sim | 4096 | Identificador único do endereço | Texto livre | CLI-4693 |
| country | String | Sim | 3 | Pais do endereço | Formato ISO 3166-1 alfa-3 | "BRA" |
| state | String | Não | 2 | Estado do endereço | Quando Brasil valida as 27 opções, se informado | SP |
| city | String | Não | 4096 | Cidade do endereço | Texto livre | Bauru |
| zipCode | String | Não | 4096 | CEP do endereço | Valida formato, se informado e se BRA | 17047-001 |
| address | String | Sim | 4096 | Rua, número, Bairro e complemento do endereço | Texto livre | Gomes de carvalho, 940 |
Layout de Resposta
| TPRGeolocationResponse: Integração rest, sincrona | ||||||
|---|---|---|---|---|---|---|
| Campo | Tipo | Obrigatório | Tamanho | Descrição | Validações | Exemplos |
| dateCall | Date Time | Sim | Data do envio da resposta no TPR | - | 2021-01-21T10:01:00.0-03:00 YYYY-MM-DDThh:mm:ss.sTZD | |
| version | String | Sim | 4096 | Versão do TPR que executou a resposta | - | 0.0.0.1 |
| success | Boolean | Sim | True se sucesso, false se falha | - | True | |
| message | TPRMessage[] | Sim | Campo que deve ser exibido pelo sistema externo para o usuário | - | ||
Layout do Call BackÂncora TPRGeolocationCB TPRGeolocationCB
| TPRGeolocationCallback: Integração rest, Assincrona | ||||||
Path: ver campo TPRGeolocation/CallbackURL, Método: POST | ||||||
| Campo | Tipo | Obrigatório | Tamanho | Descrição | Validações | Exemplos |
|---|---|---|---|---|---|---|
| dateCall | Date Time | Sim | Data do envio da resposta no TPR | Formato ISO | 2021-01-21T10:01:00.0-03:00 YYYY-MM-DDThh:mm:ss.sTZD | |
| version | String | Não | 4096 | Versão do TPR que executou a resposta | Texto Livre | 12.36.1 |
| geolocationResults | TPRGeolocationResult[] | Sim | Lista de resultados de geolocalização | - | Tabela abaixo | |
| Âncora | ||||
|---|---|---|---|---|
|
| TPRGeolocationResult, tipo de dado utilizado nas integrações do TPR | ||||||
|---|---|---|---|---|---|---|
| Campo | Tipo | Obrigatório | Tamanho | Descrição | Validações | Exemplos |
| success | Boolean | Sim | True se sucesso, false se falha | - | True | |
| identifier | String | Sim | 4096 | Identificador único do endereço | Texto livre | CLI-4693 |
| latitude | Double | Não | Latitude | Intervalo [-90; 90] | -23.6114291 | |
| longitude | Double | Não | Longitude | Intervalo [-180; 180] | -46.6946795 | |
| message | TPRMessage[] | Sim | Campo que deve ser exibido pelo sistema externo para o usuário | - | Tabela abaixo | |
| Âncora | ||||
|---|---|---|---|---|
|
TPRMessage: Tipo de dado utilizado nas integrações do TPR | ||||||
| Campo | Tipo | Obrigatório | Tamanho | Descrição | Validações | Exemplos |
| messageCode | String | Sim | 4096 | Código de identificação da mensagem | Código existente e valido | TPR0001 |
| message | String | Sim | 4096 | Mensagem escrita | Texto Livre | "Para finalizar o cadastro acesse seu e-mail e valide o Token" |
| Informações | ||
|---|---|---|
| ||
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
| TPRCatMsg | |
| TPRCatMsg |
Catálogo de Mensagens
Código | Mensagem | Descrição |
|---|---|---|
| TPRGL0000 | Sucesso | Retorno indicando sucesso da operação |
| TPRGL0001 | Data da criação da chamada no sistema externo é obrigatória | Retorno inválido para a validação do campo dateCall, já que se encontra nulo ou vazio |
| TPRGL0002 | Qualifiers 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 |
| TPRGL0003 | URL da chamada de retorno é obrigatória | Retorno inválido para a validação do campo callbackURL, já que se encontra nulo ou vazio |
| TPRGL0004 | URL de chamada de retorno deve ser HTTPS | Retorno inválido para a validação do campo callbackURL, quando não estiver utilizando o protocolo HTTPS |
| TPRGL0005 | Tipo 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 |
| TPRGL0006 | Tipo de autenticação da chamada de retorno não é válido | 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 |
| TPRGL0008 | Identificador 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 |
| TPRGL0009 | País do endereço é obrigatório | Retorno inválido para a validação do campo country do objeto address, já que se encontra nulo ou vazio |
| TPRGL0010 | País do endereço não é um país válido | 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 |
| TPRGL0011 | Estado do endereço 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 |
| TPRGL0012 | Logradouro do endereço é obrigatório | Retorno inválido para a validação do campo address do objeto address, já que se encontra nulo ou vazio |
| TPRGL0013 | Não foi possível achar a geocodificação para o endereço informado | Retorno informando que não foi possível gerar a geocodificação com as informações passada como endereço |
| TPRGL0014 | Erro ao solicitar geocodificação para o provedor | Retorno de erro ao pedir para o provedor a geocodificação com as informações passada como endereço |
| TPRGL0015 | O valor do sistema possui mais de 4096 caractere | Retorno inválido para a validação do campo system, porque é maior que 4096 caracteres |
| TPRGL0016 | O valor da versão possui mais de 4096 caracteres | Retorno inválido para a validação do campo version, porque é maior que 4096 caracteres |
| TPRGL0017 | O valor de qualifiers possui mais de 4096 caracteres | Retorno inválido para a validação do campo qualifiers, porque é maior que 4096 caracteres |
| TPRGL0018 | O 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 |
| TPRGL0019 | O 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 |
| TPRGL0020 | O 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 |
| TPRGL0021 | O valor da cidade de endereço possui mais de 4096 caracteres | Retorno inválido para a validação do campo city do objeto address, porque é maior que 4096 caracteres |
| TPRGL0022 | O valor do CEP de endereço possui mais de 4096 caracteres | Retorno inválido para a validação do campo zipCode do objeto address, porque é maior que 4096 caracteres |
| TPRGL0023 | O valor do logradouro de endereço possui mais de 4096 caracteres | Retorno inválido para a validação do campo address do objeto address, porque é maior que 4096 caracteres |
| TPRGL0024 | CEP do endereço 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 |
| TPRGL0025 | Formato inválido | Retorno indicando que a mensagem está diferente do contrato indicado acima, logo se encontra num formato inválido |
| TPRGL0026 | Campo de datetime enviado em formato inválido | Retorno indicando que algum campo que seja datetime está com formatação inválido |
| TPRGL0027 | O identificador do endereço deve ser único | Retorno inválido para a validação do campo identifier do objeto address, já que se encontrada repetido |
Anexos
| Anexos |
|---|
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas