IMPORTANTE
- 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 ERP's 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 síncrona de geolocalização;
- 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 está com o endereço mal formatado;
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
| RestTPRSyncGeolocation: Integração rest, Sincrona | ||||||
Path: https://planejamentorotasqa.totvs.com/v1/tpr-geolocation-sync 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"}) |
| address | Sim | Endereço a ser geolocalizado. | - | |||
RestTPRAddress, 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
| RestTPRSyncGeolocationResponse: 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 |
| geolocationResult | RestTPRGeolocationResult | Sim | Resultado de geolocalização. | - | Tabela abaixo | |
| RestTPRGeolocationResult, 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 | RestTPRMessage[] | Sim | Campo que deve ser exibido pelo sistema externo para o usuário. | - | Tabela abaixo | |
RestTPRMessage: 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." |
Catálogo de Mensagens
Código | Mensagem | Descrição |
|---|---|---|
| TPRGS0000 | Sucesso. | Retorno indicando sucesso da operação. |
| TPRGS0001 | 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. |
| TPRGS0002 | O valor dos qualificadores possui mais de 4096 caracteres. | Retorno inválido para a validação do campo qualifiers, porque é maior que 4096 caracteres. |
| TPRGS0003 | A geolocalização foi interrompida por exceder o tempo limite de espera. | Retorno indicando que ocorreu um timeout na geolocalização, não sendo possível gerar uma latitude e longitude para o endereço. Sendo assim, deve-se tentar enviar a request novamente. |
Todas as mensagens previstas na integração de geolocalização assíncrona também podem ser retornadas.
Anexos
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas