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: .../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" |
| String | Sim | 4096 | E-mail para validação do token e futuras interações com o cliente | E-mail válido [email protected] | "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 o 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. |
| TPRTK0029 | Email em uso para outro token. | Retorno inválido para a validação do campo email, que já está em uso por outro token. |
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). |
Anexos
