Árvore de páginas

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

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
qualifiersStringNão4096String 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"})

addressSim
Endereço a ser geolocalizado.-

RestTPRAddress, 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

RestTPRSyncGeolocationResponse: 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
geolocationResultRestTPRGeolocationResultSim
Resultado de geolocalização.-Tabela abaixo

RestTPRGeolocationResult, 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
messageRestTPRMessage[]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

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

Catálogo de Mensagens

Código

Mensagem

Descrição

TPRGS0000Sucesso.Retorno indicando sucesso da operação.
TPRGS0001Os 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.
TPRGS0002O 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

  Arquivo Modificado
Arquivo PNG TPR_Geoloc_Sinc.png TPR_Geoloc_Sinc exported to image 24 ago, 2021 by Julio Vinicius Oliveira dos Santos
Arquivo TPR_Geoloc_Sinc draw.io diagram 24 ago, 2021 by Julio Vinicius Oliveira dos Santos