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-creation, 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 ISO | 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"}) |
| identifierType | String | Não | Tipos de identificadores possíveis | CNPJ \ CPF | "CNPJ" | |
| identifier | String | Não | 4096 | Identificador único do cliente, CNPJ ou CPF | CNPJ válido; CPF válido; Precisa ser único na base; | "53.113.791/0001-22" |
| name | String | Sim | 4096 | Nome de identificação do cliente | Texto Livre | "Neolog Consultoria e Sistemas S&A" |
| shortName | String | Não | 4096 | Como o cliente gostaria de ser chamado | Texto Livre | "Neolog" |
| phone | String | Não | 4096 | Telefone para contato do cliente. | Texto Livre | +5514981595777 |
| String | Sim | 4096 | E-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; | ||||||
| Campo | Tipo | Obrigatório | Tamanho | Descrição | Validações | Exemplos |
| dateResponse | 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 | Sim | 4096 | Versão do TPR que executou a resposta | - | 0.0.0.1 |
| success | Boolean | Sim | True se sucesso, False se falha | - | True | |
| key | String | Não | 4096 | Chave bloqueada | - | |
| dateExpiration | Date Time | Não | Data do expiração do token | Formato ISO | 2021-01-21T10:01:00.0-03:00 YYYY-MM-DDThh:mm:ss.sTZD | |
| 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 válido | TPR0001 |
| message | String | Sim | 4096 | Mensagem escrita | Texto Livre | "Para finalizar o cadastro acesse seu e-mail e valide o Token". |
Catalogo de Mensagens
| Código | Mensagem | Descrição |
| TPRTK0000 | Sucesso. | Retorno indicando sucesso da operação. |
| TPRTK0001 | Erro 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. |
| TPRTK0004 | A data da chamada é obrigatória. | Retorno inválido para a validação do campo dateCall, já que se encontra nulo ou vazio. |
| TPRTK0005 | Tipo 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. |
| TPRTK0006 | Identificador é 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. |
| TPRTK0007 | CNPJ está inválido. | Retorno inválido para a validação do campo identifier, já que está diferente do formato esperado dos CNPJs. |
| TPRTK0008 | CNPJ 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. |
| TPRTK0009 | CPF está inválido. | Retorno inválido para a validação do campo identifier, já que está diferente do formato esperado dos CPFs. |
| TPRTK0010 | CPF 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. |
| TPRTK0011 | Nome é obrigatório. | Retorno inválido para a validação do campo name, já que se encontra nulo ou vazio. |
| TPRTK0012 | E-mail é obrigatório. | Retorno inválido para a validação do campo email, já que se encontra nulo ou vazio. |
| TPRTK0013 | E-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]). |
| TPRTK0014 | 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. |
| TPRTK0017 | A mensagem está mal formatada. | Retorno indicando que a mensagem está diferente do contrato acima, logo se encontra num formato inválido. |
| TPRTK0018 | Data da chamada mal formatada. | Retorno indicando que algum campo que seja do tipó datetime está com formatação inválida. |
| TPRTK0022 | Tipo 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). |
| TPRTK0023 | O valor do sistema possui mais de 4096 caracteres. | Retorno inválido para a validação do campo system, porque é maior que 4096 caracteres. |
| TPRTK0024 | 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. |
| TPRTK0025 | O valor dos qualificadores possui mais de 4096 caracteres. | Retorno inválido para a validação do campo qualifiers, porque é maior que 4096 caracteres. |
| TPRTK0026 | O valor do identificador possui mais de 4096 caracteres. | Retorno inválido para a validação do campo identifier, porque é maior que 4096 caracteres. |
| TPRTK0027 | O valor do nome possui mais de 4096 caracteres. | Retorno inválido para a validação do campo name, porque é maior que 4096 caracteres. |
| TPRTK0028 | O valor do apelido possui mais de 4096 caracteres. | Retorno inválido para a validação do campo shortName, porque é maior que 4096 caracteres. |
| TPRTK0029 | O valor do email possui mais de 4096 caracteres. | Retorno inválido para a validação do campo email, porque é maior que 4096 caracteres. |
| TPRTK0030 | Email 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. |
| TPRTK0032 | A chave do token não foi informada. | Quando é feita uma requisição sem a chave do token. |
| TPRTK0033 | A chave do token informada não foi encontrada. | Quando a chave informada não é encontrada. |
| TPRTK0034 | A 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. |
| TPRTK0035 | Seu 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. |
| 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]. | Ao tentar efetuar roteirizações e geolocalizações com pré-trial expirado ou sem limite. |
| TPRTK0037 | O 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 |
| TPRTK0038 | O identificador do plano é obrigatório. | Ao cadastrar planos novos sem identificador |
| TPRTK0039 | O plano já existe. | Ao cadastrar planos novos, que já existe o identificador cadastrado. |
| TPRTK0040 | Os planos padrões já existem. | Tentativa de criação de planos padrões |
| TPRTK0041 | O valor do campo [Nome do campo] não deve ser menor que zero. | Validação de cadastro de token |
| TPRTK0042 | Vigência não encontrada. | Acontece em integração de tokens não ativos |
| TPRTK0043 | Trial iniciado com sucesso. | Mensagem de sucesso de início de trial |
| TPRTK0044 | Tipo trial não é suportado por tokens diferentes de pré-trial. | Ao tentar colocar um plano do tipo Sale para trial. |
| TPRTK0045 | Tipo [Tipo da integração] não é suportado por tokens com plano cancelado. | Ao tentar integrar Sale/Trial em um token cancelado. |
| TPRTK0046 | Compra efetuada com sucesso. | Mensagem de sucesso de compra |
| TPRTK0047 | Tipo 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 |
| TPRTK0048 | Trial cancelado com sucesso. | Ao cancelar o trial com sucesso. |
| TPRTK0049 | O token já possui plano cancelado. | Ao tentar cancelar um token já cancelado |
| TPRTK0050 | Tipo cancel/trial-cancel só é suportado por tokens em trial. | Ao solicitar o cancelamento de tokens com planos diferentes de trial. |
| TPRTK0051 | Opção invalida. Utilize: trial/sale/cancel/trial-cancel no campo tipo. | Ao enviar integração da Store com a opção inválida. |
| TPRTK0052 | Opção de documento inválido. Utilize os formatos de CPF/CNPJ | Ao enviar integração da Store com CPF ou CNPJ com os dígitos inválidos |
| TPRTK0053 | O 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ódigo | Mensagem | Descrição |
| TPRTK0002 | Id é obrigatório | Retorno inválido para a validação de atualização de token do campo id, já que se encontra nulo ou vazio. |
| TPRTK0003 | Token não encontrado | Retorno indicando que o token que deseja fazer a operação não foi encontrado. |
| TPRTK0015 | Data de expiração é obrigatório | Retorno inválido para a validação do campo expirationDate, já que se encontra nulo ou vazio. |
| TPRTK0016 | Data de expiração está inválida | Retorno inválido para a validação do campo expirationDate, já que está sendo escolhida uma data de expiração no passado. |
| TPRTK0019 | Nome do campo a ser filtrado é obrigatório | Retorno inválido para a validação do campo fieldName para filtro, já que se encontra nulo ou vazio. |
| TPRTK0020 | Valor do filtro é obrigatório | Retorno inválido para a validação do campo value para filtro, já que se encontra nulo ou vazio. |
| TPRTK0021 | Nome do campo a ser filtrado está inválido | Retorno 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). |
| TPRTK0054 | Token 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
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas