Page Comparison

Essa área tem como objetivo descrever cenários de casos de uso comuns na utilização da API de Integração para que sirva de guia para desenvolvedores. Caso você tenha um cenário de uso diferente, entre em contato com nosso time de suporte através do nosso canal de atendimento: privacytools.com.br/help

Cenário 1 - Coletando consentimentos de usuários (anônimos ou não)

Nesse cenário de integração você precisa coletar e armazenar consentimentos de usuários.

Motivação: Através desse recurso a empresa possui a rastreabilidade dos consentimentos e possui meios de comprovação que os consentimentos foram coletados de maneira segura e eficiente.

Como fazer:

Cenário 2 - Tenho uma base de dados com vários consentimentos já coletados, quero colocar todos eles no sistema para passar a gerencia-los por aí

Nesse caso você precisa fazer uma integração utilizando as API’s privadas de backend, não as API’s públicas de frontend.

1. Acesse o menu “ConformidadePrivacidade/Consentimentos/API integração” e escolha a aba “Integre com a sua aplicação”

2. Tome nota das chaves de integração, como o hash do Authorization, que pode ser Basic ou Oauth2(Bearer) e é de acordo com qual versão da api_external que a empresa estiver usando.

3. Na mesma tela você possui disponível a API de integração exposta no formato Swagger.IO. Caso queira estudar a documentação fora da plataforma acesse a página “Backend/Swagger” ao lado.

4. Registre (caso não tenha registrado ainda) a finalidade do consentimento que será importado e copie a chave do consentimento (hashTemplate). Criar os grupos e as finalidades, clique neste link de documentação.

Obs.: Para todos os campos string não há limite de caracteres.

Objeto para importação de um titular e seu consentimento, utilize o serviço abaixo:

5. Após a chamada da importação acima o sistema irá procurar algum titular com o mesmo hashUser. Caso não encontre ele criará um novo titular com os dados pessoais submetidos e com o hashUser. Ao final do processo ele registrará o resultado do consentimento para a finalidade sugerida.

Obrigatoriedade dos campos do Body

• Titular já existe na base de dados

Para identificar o Titular, pelo menos um dos campos deve ser informado: hashUser, document ou email. Se for informado mais de um destes campos, a busca por titular é feita nesta ordem: hashUser, document, email.

• Titular não existe na base de dados (cadastro de titular)

Se o Titular não for encontrado pelos campos hashUser, document ou email, o sistema tentará fazer um novo cadastro. Neste caso, os campos obrigatórios são: name, email e document. 

• Registro de consentimento

Para registrar o consentimento, são obrigatórios: templateHash e consentValue. Se não informar estes dois campos, o titular é cadastrado (se não existir), porém não será registrado consentimento.

Response

Se for informado o templateHash e o consentValue, retorna o hash do consentimento

Senão, retorna o hash do Titular. Se for cadastro de Titular, o hash será o informado no campo hashUser. Se não informar hashUser, será gerado um baseado nos campos name, email, document e phone.

Descriminação de saída segundo o código:

• 200 (ok) =

  se user.templateHash não é nulo e nem em branco e
    user.consentValue não é nulo, retorna consent.hashConsent (string)

se não retorna person.hash (string)

• 400 (bad request) =

  Caso user for nulo retorna "No valid templateHash" (string);

  Caso user.hashUser não é nulo e não está em branco lista todas os consentimentos de pessoas referente a company e se a lista estiver vazia então user.name e user.email são obrigatórios caso contrário retorna "No valid user data. Required fields: name, email and document." (string);

Cenário 3 - Quero verificar se o usuário já deu consentimento, caso contrário solicitar consentimento

Esse tipo de cenário é útil em casos onde você quer validar se o seu usuário, normalmente logado, já aceitou algum termo específico do seu negócio, e caso negativo, mostrar algum alerta, bloqueio, ou mensagem solicitando a concordância.

Passo 1 - Verificar se o usuário já deu o consentimento

O primeiro passo é a verificação se o usuário já fez o consentimento e qual foi a sua resposta. Você pode fazer isso tanto na sua aplicação backend, quanto na sua aplicação frontend.

Endpoint: /external_api/consent/check/{templateHash}/{userHash}
Method: GET

Retorno: 
Lista em ordem decrescente
de todos os consentimentos desse titular
para essa condição. Considere a primeira
da lista como a mais recente. 

Argumentos:
$templateHash -Hash da finalidade do 
consentimento que você quer verificar
$userHash - Hash de identificação
do titular a ser verificado

Passo 2 - Buscando o consentimento do titular

Agora que você já verificou se o titular consentiu ou não com a sua finalidade, é a hora de ir em busca do consentimento ou tomar outras ações caso você já tenha o consentimento. Esse fluxo de decisão faz parte do negócio do cliente e deve ser desenvolvido na plataforma correta.

Para realizar a coleta do consentimento leia o caso de uso 1 “Cenário 1 - Coletando consentimentos de usuários” nessa página.

Cenário 4 - Vários registros anônimos vinculados com um mesmo titular

Status
colour Yellow title Em melhoria

Nesse caso temos a situação onde você possui a geração de diversos $hashUser anônimos mas no final do processo você quer vincular todos com o mesmo titular.

Como fazer:

1. Faça a geração do seu $hashUser anônimo para gravação de consentimentos e registre-os normalmente.

2. Quando for o momento de reidentificar um titular, utilize o serviço de backend '${base}/consent/reidentify-id/$hashUser/{email}/{document}'

3. Caso o email e documento do titular não exista na base de dados ele irá criar um novo titular e depois ele irá reidentificar todos os consentimentos registrados com o $hashUser

4. Caso o titular já exista na base de dados ele irá apenas reidentificar todos os consentimentos registrados com o $hashUser que você enviou por parâmetro, mas o titular já cadastrado permanecerá com o $hashUser original.

Esse cenário 4 foi marcado como

Cenário 5 - Tenho diversos dispositivos e sistemas , o meu usuário precisa conceder o consentimento em todos eles?

Não. Se você utilizar o mesmo $hashUser não importa qual o dispositvo verificador, o estado do consentimento/autorização será o mesmo.

Por esse motivo recomendamos definir logo no início do projeto qual será a forma de criação do $hashUser em todos os sistemas que irão consultar consentimentos.

IMPORTANTE: Se você chegou até aqui e não sabe o que significa o “hashUser” e o “hashTemplate”, leia a sessão https://privacyts.atlassian.net/wiki/spaces/GSD/pages/5079309/API+-+Integra+es#Como-obter-o-hashTemplate%3F antes de prosseguir.

Cenário 6 - Meu formulário precisa registrar diversos consentimentos ao mesmo tempo, como fazer?

Considere o exemplo abaixo. Uma interface que precisa registrar 3 autorizações diferentes do usuário:

• Autorização 1 - Finalidade obrigatória relacionada ao termo de uso e à prestação do servição em si.

• Autorizações 2 e 3 - Outras finalidades opcionais que dependem do consentimento do usuário

Quando o usuário clicar em “Aceitar” você tem 2 alternativas: