IMPORTANTE
- A integração TOTVS OMS x TOTVS Planejamento de Rotas (TPR) será descontinuada no próximo release (Outubro/2023).
Introdução
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;
- 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;
Layout de Requisição
| TPRGeolocation: Integração rest, Assíncrona com a TPRGeolocationCB | ||||||
Path: https://planejamentorotasqa.totvs.com/v1/tpr-geolocation Método: POST Header obrigatório: Chave = "TPR_AUTHORIZATION" e Valor = Chave gerada na integração de Criação de token | ||||||
| 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 | String | Não | 4096 | String 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":"Pedro", "Perfil":"Analista"}) |
| callbackURL | String | Sim | 4096 | URL de Call Back. | Inicio com "https://" quando o tipo de autenticação for diferente de NONE | |
| 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== |
| addresses | Sim | Lista de endereços a serem geolocalizados. | - | |||
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
| 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 |
| qualifiers | String | Não | 4096 | String 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":"Pedro", "Perfil":"Analista"}) |
| geolocationResults | TPRGeolocationResult[] | Sim | Lista de resultados de geolocalização. | - | Tabela abaixo | |
| 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 | |
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." |
Retorno 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.
Catálogo de Mensagens
Código | Mensagem | Descrição |
|---|---|---|
| TPRGL0000 | Sucesso. | Retorno indicando sucesso da operação. |
| TPRGL0001 | A data da chamada é obrigatória. | Retorno inválido para a validação do campo dateCall, já que se encontra nulo ou vazio. |
| TPRGL0002 | 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. |
| 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 | Para utilizar autenticação, a 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 com o tipo de autenticação diferente de NONE |
| 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 | O 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. |
| 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 | O 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. |
| TPRGL0010 | O 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. |
| TPRGL0011 | O 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. |
| TPRGL0012 | O 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. |
| TPRGL0013 | Nã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. |
| TPRGL0014 | Erro interno, tente novamente e se o problema persistir contate: [EMAIL_SUPORTE]. | 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 caracteres. | 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 dos qualificadores 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 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. |
| TPRGL0022 | O 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. |
| TPRGL0023 | O 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. |
| TPRGL0024 | O 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. |
| TPRGL0025 | A mensagem está mal formatada. | Retorno indicando que a mensagem está diferente do contrato indicado acima, logo se encontra num formato inválido. |
| TPRGL0026 | Data da chamada mal formatada. | Retorno indicando que algum campo que seja datetime está com formatação inválido. |
| TPRGL0027 | O 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. |
| TPRGL0028 | Valor 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. |
| TPRTK0032 | A chave do token não foi informada. | Retorno inválido para requisição que não envia o header "TPR_AUTHORIZATION" com a chave do token. |
| TPRTK0033 | A chave do token informada não foi encontrada. | Retorno inválido para requisição que enviar uma chave no header "TPR_AUTHORIZATION" que não existe na base de dados. |
| TPRTK0034 | A vigência do seu plano chegou ao fim. Para reativar refaça o cadastro. | Retorno inválido para requisição que enviar uma chave no header "TPR_AUTHORIZATION" que não tenha um plano vigente. |
| TPRTK0035 | Seu plano mensal já foi consumido. | Retorno inválido para requisição que enviar uma chave no header "TPR_AUTHORIZATION" que já tenha consumido toda quota de rotas e/ou roteirizações do plano vigente. |
| TPRTK0036 | O seu período de pré-trial acabou! Você ainda pode experimentar o TOTVS PLANEJAMENTO DE ROTAS por 30 dias, gratuitamente, assinando o Trial através da TOTVS Store [Link TOTVS Store]. | Retorno inválido para requisição que enviar uma chave no header "TPR_AUTHORIZATION" que já tenha consumido toda quota de roteirizações ou finalizado o tempo de "TRIAL" |
| TPRTK0037 | O seu trial chegou ao fim. Para continuar usando o Totvs Planejamento de Rotas, faça a contratação acessando "https://partner.totvs.store/br/produto/totvs-planejamento-de-rotas.html". | Retorno inválido para requisição que enviar uma chave no header "TPR_AUTHORIZATION" que já tenha finalizado o tempo de "TRIAL" |
Anexos
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas