Introdução

A API de Link Único foi desenvolvida para simplificar e personalizar o acesso dos colaboradores as pesquisas: ela permite a disponibilização de um link único de respostas às pesquisas que podem ser realizadas de diferentes formas.

 

Atualmente nossa plataforma pode disparar as pesquisas por e-mail, sms, Teams, Slack e Workplace, entretanto nem todos os colaboradores tem acesso a essas plataformas. A API possibilita que os seus colaboradores respondam as perguntas da forma que melhor funcionar para a realidade da sua empresa!

Utilizando o CPF do colaborador como referência, a API gera um link único que redireciona o usuário diretamente para o formulário de respostas, melhorando a experiência do usuário e aumentando a eficiência do processo. Esse link pode ser enviado de acordo com a sua necessidade. Por exemplo, você pode disponibilizar esse link dentro de um totem, um site interno ou até disparar por um canal diferente, como Whatsapp.

 

Objetivos e benefícios

• Expansão das pesquisas para maior número de colaboradores;
• Acesso rápido e direto a formulários;
• Processos de envio de formulários automatizados, permitindo que os sistemas internos dos clientes gerem e distribuam links sem intervenção manual.

Como utilizar

O administrador da plataforma precisa gerar o token para a integração da API clicando em "Configurações > App de Integração > Gerar Token":

 

O token de autenticação é único para cada empresa e deve ser usado para gerar o hash JWT, substituindo `<token>` no endpoint correspondente.

 

Endpoints de Referência

 

Ambiente de Produção

Gerador de Hash JWT

- Método: GET
- URL: `https://magnus.mereo.com/api/v1/service/generateKey/jwt/<token>`

Gerador de Link Único

- Método: POST
- URL: `https://magnus.mereo.com/api/v1/service/getuserlink`

 

Uso da API

Gerador de Hash JWT

Requisição

- Método: GET
- URL: `https://magnus.mereo.com/api/v1/service/generateKey/jwt/<token>`

 

Resposta de Sucesso

{
  "value": {
    "code": 200,
    "status": "success",
    "message": "Valid login credentials",
    "key": "<UNIQUE_KEY>",
    "jwt": "<JWT_TOKEN>"
  }
}

Resposta de Erro

{
  "value": "Token inválido!"
}

Nota: O hash JWT é válido por 60 segundos. Após esse período, é necessário gerar um novo hash.

 

Gerador de Link Único

Requisição

- Método: POST
- URL: `https://magnus.mereo.com/api/v1/service/getuserlink`

Body (formato JSON)

{
  "cpf": "11928741425"
}
```
ou
```json
{
  "cpf": "119.287.414-25"
}

Headers

Authorization: <JWT_TOKEN>

 

Resposta de Sucesso

{
  "code": 200,
  "success": {
    "mensagem": "https://shortener.vaipe.com/abd123"
  }
}

Exemplo de respostas de erros

{
  "code": 200,
  "error": {
    "mensagem": "Authentication failed: Expired token"
  }
}

{
  "code": 200,
  "error": {
    "mensagem": "CPF não é válido. Por favor, insira um cpf válido."
  }
}

{
  "code": 200,
  "error": {
    "mensagem": "CPF não cadastrado na plataforma"
  }
}

{
  "code": 200,
  "error": {
    "mensagem": "Colaborador não tem perguntas para responder!"
  }
}

 

Regras para Geração do Link

- O CPF deve ser válido e formatado corretamente.
- O CPF deve estar associado a um colaborador vinculado à empresa do token utilizado.
- O colaborador deve ter perguntas pendentes e ativas na plataforma.
- O link único é gerado a cada requisição, garantindo que cada acesso seja único e seguro.

 

Segurança e Privacidade

- A API utiliza autenticação baseada em tokens e JWT para garantir a segurança do acesso aos formulários.
- É essencial que os tokens e JWT sejam gerenciados de forma segura, seguindo as melhores práticas de segurança da informação.
- É recomendado ter algum nível de autenticação do lado do cliente para evitar que colaboradores respondam as pesquisas de outros colaboradores.

 

Suporte e Contato

Para dúvidas ou suporte técnico relacionado à API de Link Único, entre em contato com a equipe de suporte da plataforma através dos canais oficiais.

 

Mudanças Visíveis na Interface dos Usuários

A integração pode resultar em mudanças mínimas ou nenhuma na interface do usuário, dependendo de como a API é implementada. O objetivo principal é simplificar o acesso aos formulários, portanto, as mudanças seriam principalmente no backend e na forma como os links são gerados e distribuídos.

 

Informações para o Administrador e Aspectos Técnicos

Os administradores precisarão entender como:
- Obter e gerenciar o token de autenticação exclusivo da empresa.

 

Aspectos técnicos incluem:
- Compreensão dos métodos HTTP (GET para gerar o JWT e POST para gerar o link único).
- Formatação correta do corpo da requisição (JSON) e dos cabeçalhos (headers) para autenticação.

 

Ambos:
- Tratamento de erros e validação de CPFs.

 

Impacto na Segurança e Privacidade dos Dados

A integração aumenta a segurança ao utilizar tokens e JWT para autenticação e autorização, reduzindo o risco de acesso não autorizado. A privacidade dos dados é mantida. É recomendado ter algum nível de autenticação do lado do cliente para evitar que colaboradores respondam as pesquisas de outros colaboradores. É importante garantir que os tokens e JWT sejam gerenciados de forma segura para minimizar riscos.