Árvore de páginas

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

  • "Hand shake" entre o TPR e o sistema externo, resulta na criação de token de acesso para o cliente, que após validado via e-mail liberará o acesso ao sistema via trial de acordo com o fluxo:


Pré-requisitos instalação/implantação/utilização

  • Para clientes Protheus versão xxxxxx;
  • Para clientes Datasul versão xxxxxx;
  • Para todos os clientes, contratação do trial via TOTVS Store;

Layout de Requisição

TPRTokenIntegration: Integração rest, sincrona

Path: https://planejamentorotasqa.totvs.com/v1/tpr-token-creationMétodo: POST

CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
dateCallDate TimeSim
Data da criação da chamada no sistema externoFormato ISO2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD
systemStringNão4096Identificador do sistema que fez a chamadaTexto LivreProtheus
versionStringNão4096Versão do sistema externoTexto 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"})

identifierTypeStringNão
Tipos de identificadores possíveisCNPJ \ CPF"CNPJ"
identifierStringNão4096Identificador único do cliente, CNPJ ou CPFCNPJ válido;
CPF válido;
Precisa ser único na base;
"53.113.791/0001-22"
nameStringSim4096Nome de identificação do clienteTexto Livre"Neolog Consultoria e Sistemas S&A"
shortNameStringNão4096Como o cliente gostaria de ser chamadoTexto Livre"Neolog"
phoneStringNão4096Telefone para contato do cliente.Texto Livre+5514981595777
emailStringSim4096E-mail para validação do token e futuras interações com o cliente

E-mail válido [email protected];

Precisa ser único na base;

"neolog@neolog.com.br"

Layout de Resposta

TPRTokenResponse: Integração rest, sincrona;
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
dateResponseDate TimeSim
Data do envio da resposta no TPRFormato ISO2021-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
keyStringNão4096Chave bloqueada-
dateExpirationDate TimeNão
Data do expiração do tokenFormato ISO2021-01-21T10:01:00.0-03:00
YYYY-MM-DDThh:mm:ss.sTZD
messageTPRMessage[]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
CampoTipoObrigatórioTamanhoDescriçãoValidaçõesExemplos
messageCodeStringSim4096Código de identificação da mensagemCódigo existente e válidoTPR0001
messageStringSim4096Mensagem escritaTexto Livre"Para finalizar o cadastro acesse seu e-mail e valide o Token".

Catalogo de Mensagens

CódigoMensagemDescrição
TPRTK0000Sucesso.Retorno indicando sucesso da operação.
TPRTK0001Erro interno, tente novamente e se o problema persistir contate: [EMAIL_SUPORTE].Retorno de erro para problemas em algum serviço externo, normalmente conexão com o banco de dados ou de pubsub.
TPRTK0004A data da chamada é obrigatória.Retorno inválido para a validação do campo dateCall, já que se encontra nulo ou vazio.
TPRTK0005Tipo de identificador é obrigatório ao informar o identificador.Retorno inválido para a validação do campo identifierType, já que se encontra nulo ou vazio quando informado o identificador.
TPRTK0006Identificador é obrigatório ao informar o tipo de identificador.Retorno inválido para a validação do campo identifier, já que se encontra nulo ou vazio quando informado o tipo de identificador.
TPRTK0007CNPJ está inválido.Retorno inválido para a validação do campo identifier, já que está diferente do formato esperado dos CNPJs.
TPRTK0008CNPJ já está em uso para outro token.Retorno inválido para a validação do campo identifier, já que está sendo usado em outro registro.
TPRTK0009CPF está inválido.Retorno inválido para a validação do campo identifier, já que está diferente do formato esperado dos CPFs.
TPRTK0010CPF já está em uso para outro token.Retorno inválido para a validação do campo identifier, já que está sendo usado em outro registro.
TPRTK0011Nome é obrigatório.Retorno inválido para a validação do campo name, já que se encontra nulo ou vazio.
TPRTK0012E-mail é obrigatório.Retorno inválido para a validação do campo email, já que se encontra nulo ou vazio.
TPRTK0013E-mail está inválido.Retorno inválido para a validação do campo email, já que está diferente do formato esperado de um e-mail ([email protected]).
TPRTK0014Os 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.
TPRTK0017A mensagem está mal formatada.Retorno indicando que a mensagem está diferente do contrato acima, logo se encontra num formato inválido.
TPRTK0018Data da chamada mal formatada.Retorno indicando que algum campo que seja do tipó datetime está com formatação inválida.
TPRTK0022Tipo de identificador está inválido.Retorno inválido para a validação do campo identifierType, já que se encontra diferente dos valores possíveis (CPF, CNPJ).
TPRTK0023O valor do sistema possui mais de 4096 caracteres.Retorno inválido para a validação do campo system, porque é maior que 4096 caracteres.
TPRTK0024O valor da versão possui mais de 4096 caracteres.Retorno inválido para a validação do campo version, porque é maior que 4096 caracteres.
TPRTK0025O valor dos qualificadores possui mais de 4096 caracteres.Retorno inválido para a validação do campo qualifiers, porque é maior que 4096 caracteres.
TPRTK0026O valor do identificador possui mais de 4096 caracteres.Retorno inválido para a validação do campo identifier, porque é maior que 4096 caracteres.
TPRTK0027O valor do nome possui mais de 4096 caracteres.Retorno inválido para a validação do campo name, porque é maior que 4096 caracteres.
TPRTK0028O valor do apelido possui mais de 4096 caracteres.Retorno inválido para a validação do campo shortName, porque é maior que 4096 caracteres.
TPRTK0029O valor do email possui mais de 4096 caracteres.Retorno inválido para a validação do campo email, porque é maior que 4096 caracteres.
TPRTK0030Email em uso por outro token.Retorno inválido para a validação do campo email, que já está em uso por outro token.
TPRTK0031

O plano [IDENTIFICADOR_PLANO] não foi encontrado, contate: [EMAIL_SUPORTE].

Retorno inválido quando é tentado criar um token mas o plano Pré-Trial não está cadastrado na base de dados.
TPRTK0032A chave do token não foi informada.Quando é feita uma requisição sem a chave do token.
TPRTK0033A chave do token informada não foi encontrada.Quando a chave informada não é encontrada.
TPRTK0034A vigência do seu plano chegou ao fim. Para reativar refaça o cadastro.Quando termina a vigência do plano e não é renovada.
TPRTK0035Seu plano mensal já foi consumido, para continuar utilizando o produto acesse 'Meu Plano' e configure o consumo fora do pacote.Ao tentar efetuar roteirização com bloqueio de uso de rotas fora do pacote.
TPRTK0036O 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].Ao tentar efetuar roteirizações e geolocalizações com pré-trial expirado ou sem limite.
TPRTK0037O seu trial chegou ao fim. Para continuar usando o Totvs Planejamento de Rotas, faça a contratação acessando [Link TOTVS Store].Ao tentar efetuar roteirizações e geolocalizações com trial expirado
TPRTK0038O identificador do plano é obrigatório.Ao cadastrar planos novos sem identificador
TPRTK0039O plano já existe.Ao cadastrar planos novos, que já existe o identificador cadastrado.
TPRTK0040Os planos padrões já existem.Tentativa de criação de planos padrões
TPRTK0041O valor do campo [Nome do campo] não deve ser menor que zero.Validação de cadastro de token
TPRTK0042Vigência não encontrada.Acontece em integração de tokens não ativos
TPRTK0043Trial iniciado com sucesso.Mensagem de sucesso de início de trial
TPRTK0044Tipo trial não é suportado por tokens diferentes de pré-trial.Ao tentar colocar um plano do tipo Sale para trial.
TPRTK0045Tipo [Tipo da integração] não é suportado por tokens com plano cancelado.Ao tentar integrar Sale/Trial em um token cancelado.
TPRTK0046Compra efetuada com sucesso.Mensagem de sucesso de compra
TPRTK0047Tipo sale só é suportado por tokens em pré-trial ou trial.Ao tentar integrar o tipo Sale com os planos que não sejam Trial e Pré-Trial
TPRTK0048Trial cancelado com sucesso.Ao cancelar o trial com sucesso.
TPRTK0049O token já possui plano cancelado.Ao tentar cancelar um token já cancelado
TPRTK0050Tipo cancel/trial-cancel só é suportado por tokens em trial.Ao solicitar o cancelamento de tokens com planos diferentes de trial.
TPRTK0051Opção invalida. Utilize: trial/sale/cancel/trial-cancel no campo tipo.Ao enviar integração da Store com a opção inválida.
TPRTK0052Opção de documento inválido. Utilize os formatos de CPF/CNPJAo enviar integração da Store com CPF ou CNPJ com os dígitos inválidos
TPRTK0053O número de telefone está inválido.Na criação de um token quando é informado um telefone com formato inválido.
TPRTK0055
Token não ativo. É necessário estar ativo para o fluxo trial/sale/cancel.
Ao enviar integração da Store quando token não for ativo.

Catalogo de Mensagens Internas

CódigoMensagemDescrição
TPRTK0002Id é obrigatórioRetorno inválido para a validação de atualização de token do campo id, já que se encontra nulo ou vazio.
TPRTK0003Token não encontradoRetorno indicando que o token que deseja fazer a operação não foi encontrado.
TPRTK0015Data de expiração é obrigatórioRetorno inválido para a validação do campo expirationDate, já que se encontra nulo ou vazio.
TPRTK0016Data de expiração está inválidaRetorno inválido para a validação do campo expirationDate, já que está sendo escolhida uma data de expiração no passado.
TPRTK0019Nome do campo a ser filtrado é obrigatórioRetorno inválido para a validação do campo fieldName para filtro, já que se encontra nulo ou vazio.
TPRTK0020Valor do filtro é obrigatórioRetorno inválido para a validação do campo value para filtro, já que se encontra nulo ou vazio.
TPRTK0021Nome do campo a ser filtrado está inválidoRetorno inválido para a validação do campo fieldName para filtro, já que está fora das opções dos campos que podem ser filtrados (identifier, name, shortName, email, active).
TPRTK0054Token não encontrado, verifique se o token foi ativado através de seu email ou se a chave foi inserida incorretamente.Retorno para o front-end quando o token não foi ativo ou a chave estiver incorreta.

Anexos

  Arquivo Modificado
Arquivo PNG TPR_token_macro.png TPR_token_macro exported to image 06 abr, 2021 by Julio Vinicius Oliveira dos Santos
Arquivo TPR_token_macro draw.io diagram 06 abr, 2021 by Julio Vinicius Oliveira dos Santos
Arquivo PNG TPR_token.png TPR_token exported to image 06 abr, 2021 by Julio Vinicius Oliveira dos Santos
Arquivo TPR_token draw.io diagram 06 abr, 2021 by Julio Vinicius Oliveira dos Santos