Instruções para Integração

O que é?

Esta área é dedicada exclusivamente à orientação de desenvolvedores e integradores da plataforma PrivacyTools em sistemas.

Passo a Passo

Variáveis e Chaves

Para utilizar a API e o SDK abaixo, você precisará ter em mãos algumas chaves ou códigos que estão disponíveis na conta da sua plataforma PrivacyTools. Caso tenha dificuldade em localizá-los, entre em contato com o suporte técnico.

Variável	Significado	Onde encontrar
base	A URL base do seu ambiente PrivacyTools.	Menu 'Consentimentos / API de Integração'.
publicKey ou publicAuthorization	Chave pública para utilização de alguns recursos.	Menu 'Consentimentos / API de Integração' Aba: "Integre com seu website"
hashTemplate	Código hash da finalidade específica.	Menu 'Consentimentos / Finalidades', escolha o grupo e, em seguida, copie o hash da finalidade.
hashUser	Hash do identificador do titular do dado pessoal (usuário).	Você deve gerar esse hash. Recomendamos usar um algoritmo MD5 ou SHA do ID do usuário combinado com um SALT.

Como obter o hashTemplate?

Quando um titular precisa consentir com uma condição específica em seu site ou sistema, essa condição precisa estar registrada na plataforma de gerenciamento de privacidade. O hashTemplate é um código identificador dessa condição, permitindo que você acompanhe, através de dashboards e auditoria, exatamente qual condição cada usuário concordou ou discordou.

Para obter um hashTemplate, siga o passo a passo abaixo:

Acesse o menu Privacidade / Consentimentos / Finalidades.
Escolha (ou crie) um grupo de finalidades e clique no botão + Finalidades.
Caso já existam finalidades, o hashTemplate será apresentado na lista como Hash do registro.
Caso não exista nenhuma finalidade, clique no botão Adicionar para criar a sua primeira finalidade

Título	Descreva um título para essa finalidade. Depois você poderá usar esse título em uma janela para pedir consentimento do usuário.
Código	Código identificador para uso interno e controle.
Tipo	Escolha o tipo de finalidade. Pode ser uma finalidade para coleta de dados pessoais ou apenas um pedido de concordância de alguma condição.
Status	Você pode ativar ou desativar finalidades.
Retenção (em dias)	Caso o titular dê o consentimento em uma determinada data, o sistema irá revogar o consentimento após essa quantidade de dias.
Finalidade do consentimento	Explique o motivo pelo qual você precisa desse consentimento do usuário.
Exigência	NÃO = O consentimento é livre e opcional, respeitando o princípio da LGPD. SIM = O consentimento por padrão é “SIM”, não seguindo o princípio de PbD. ATIVO = O consentimento é sempre ativo, não há opção para troca, não seguindo os princípios. A ferramenta oferece as opções acima para atender os requisitos de negócio e apetite de risco de cada organização. Recomendamos, por boa prática, manter esse campo como “NÃO”.
URL’s	Após autorização: Quando o titular concordar com essa finalidade, para qual URL você quer direcioná-lo? Após rejeição: Quando o titular rejeitar essa finalidade, para qual URL você quer direcioná-lo? Você pode usar o coringa/parâmetro “consentHash” para checar na sua URL de destino qual foi a resposta do titular. O consentHash é o recibo/comprovante de que o consentimento foi registrado com sucesso.
Dados pessoais	Você pode listar todos os dados pessoais que são tratados a partir do consentimento do usuário. Isso serve para demonstrar transparência de forma simples, para que o usuário saiba quais dados serão envolvidos após ele concordar com a finalidade.
HTML da Popup	O campo Conteúdo HTML do corpo da popup permite criar um conteúdo adicional no formato HTML para exibir na popup de pedido de consentimento. Você pode colocar links, textos, etc.

5. Pronto! Basta salvar, e você já terá uma finalidade cadastrada com um hashTemplate gerado, pronto para ser utilizado em suas integrações.

Como gerar um hashUser?

O hashUser serve para gerar um identificador único (UUID) do titular do dado pessoal, de forma que, para a plataforma de gerenciamento da privacidade, ele não tenha nenhum significado, mas para o cliente, ele funcione como um meio de identificar o titular, utilizando seus próprios métodos.

Dica, você pode usar o site SHA256 para testar diferentes algoritmos de hash e gerar o hashUser ou outros tipos de hash.

Exemplos:

Base de dados do cliente:

ID: 10001
EMAIL: joao@cliente.com.br
CPF: 000.000.000-60

Os três atributos ao lado formam um identificador único do usuário.

A empresa pode criar um SALT, que é uma senha complementar usada para dificultar a reversão do hash, tornando o processo de geração do identificador mais seguro.

Exemplo de SALT: #EMP#@!1388979!@^A

Para gerar o hashUser, você pode utilizar um algoritmo de hash como MD5 ou SHA256. Aqui está um exemplo de como concatenar os atributos do usuário e gerar o hash:

Exemplo:

ID + EMAIL + CPF = 10001joao@cliente.com.br000.000.000-60
ID + EMAIL + CPF + SALT = 10001joao@cliente.com.br000.000.000-60#EMP#@!1388979!@^A

Resultados dos algoritmos de hash:

MD5 = 426a562aa633b781802c9b5be3efeca6
SHA256 = b617a4b252754717b45baddc7f73d9d8cfb589d58b7bc1d5809ea234a5065fc6

No exemplo acima, tanto o MD5 quanto o SHA256 poderiam ser usados como o seu hashUser. Embora esse seja um caso fictício, é importante notar que existem métodos mais simples para gerar um ID único. O fundamental é garantir que o ID não seja sequencial (como 10001, 10002, 10003) ou facilmente previsível, como um MD5 gerado a partir de números inteiros ou dados codificados em Base64.

E quando o usuário é anônimo, como gerar o hashUser?

No caso de usuários anônimos, ou seja, quando não se tem conhecimento sobre sua identidade, recomendamos utilizar um conjunto de atributos da navegação do usuário como base para a geração do hash. Esses atributos devem ser escolhidos de forma a torná-lo único, garantindo a maior precisão possível.

Dica. veja como funciona o AMIUnique e você pode encontrar excelentes ferramentas aqui: FingerprintJS GitHub, FingerprintJS2 GitHub e FingerprintJS.

Exemplos de atributos que podem ser usados para gerar um hash único:

JSESSION ID (aplicações Java Web)
IP
Cabeçalhos do navegador

Não tenho condições de desenvolver isso, tem algum serviço fácil para gerar o hashUser?

Sim, consulte a API do Backend no serviço "/external_api/consent/generateHashUser".

Com esse serviço, você envia os dados básicos do titular e ele gera o hashUser para você. O serviço não armazena nenhum dado, ele apenas calcula o hash em tempo real e devolve o valor para utilização.

Tipos de erros comuns

1	404	Será lançado quando não houver nenhum serviço que atenda à sua necessidade. Verifique se o método (GET/POST/DELETE/PUT) está correto e se a URL está correta.
2	400	O erro BAD REQUEST será retornado quando valores inválidos forem enviados nos parâmetros.
3	403	O erro FORBIDDEN será retornado quando chaves inválidas forem usadas, chaves de autorização expiradas, ou quando a URL invocadora não tiver permissão, ou ainda em outros casos relacionados a critérios de permissão.

Ficou com dúvidas? Chame o Time de Suporte 👈