Instruções para Integração

Esta área é dedicada exclusivamente para orientação de desenvolvedores e integradores da plataforma PrivacyTools em sistemas. Caso você busque por suporte técnico faça a abertura de um chamado em https://www.privacytools.com.br/help/

Variáveis e chaves

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

Variável	Significado	Onde encontrar
base	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 depois copie o hash da finalidade
hashUser	Hash do identificador do titular do dado pessoal (usuário)	Você deve gerar esse hash. Recomendamos um MD5/SHA do ID do usuário + algum SALT.

Como obter o hashTemplate?

Quando um titular precisa consentir com alguma determinada condição em seu site ou sistema, essa condição precisa existir na plataforma de gerenciamento da privacidade. O hashTemplate nada mais é do que um código identificador da condição para que você possa acompanhar 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 é apresentado na lista como “Hash do registro”
Caso não exista, 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 que 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 direciona-lo? Após rejeição: Quando o titular rejeitar essa finalidade, para qual URL você quer direciona-lo? Dica: 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 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 uma forma simples para que o usuário saiba quais dados seus 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á possui uma finalidade cadastrada com um “hashTemplate” gerado para poder utilizar em suas integrações.

Como gerar um hashUser?

O “hashUser” serve para você gerar um identificador único (UUID) do titular do dado pessoal de modo que, para a plataforma de gerenciamento da privacidade ele não tenha nenhum significado, mas para o cliente ele sirva como meio de identificar o titular usando meios próprios.

Dica: Você pode usar o site https://emn178.github.io/online-tools/sha256.html para testar diferentes algoritmos de hash

Exemplo:

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 do usuário.

A empresa pode criar um “SALT”, ou seja, uma senha complementar para dificultar a reversão do hash.

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

Para gerar o hashUser você pode utilizar um algoritmo de hash como MD5 ou SHA256. 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

MD5 = 426a562aa633b781802c9b5be3efeca6

SHA256 = b617a4b252754717b45baddc7f73d9d8cfb589d58b7bc1d5809ea234a5065fc6

No exemplo acima, tanto o MD5 quanto o SHA256 poderiam ser o seu hashUser. Esse exemplo é obviamente um caso fictício uma vez que você pode usar meios mais simples de geração de um ID único. O importante é que não seja um ID sequencial (10001,10002,10003) ou muito fácil de inferir como um MD5 de números inteiros ou mesmo dados codificados em Base64.

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

No caso de usuários anônimos, ou seja, você não possui conhecimento sobre a sua identidade, recomendamos utilizar como argumentos para geração do Hash um conjunto de atributos da navegação do usuário que possam torná-lo único com a maior precisão possível.

Dica: Veja como funciona o https://amiunique.org/ e você pode encontrar excelentes ferramentas aqui https://github.com/Valve/fingerprintjs https://github.com/fingerprintjs/fingerprintjs2 e https://fingerprintjs.com/

Exemplos:

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 na API do Backend o serviço “/external_api/consent/generateHashUser”

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

Tipos de erros comuns

1	404	Será lançado quando não existir nenhum serviço que lhe atenda. Confira se o método está correto (GET/POST/DELETE/PUT) e se a URL está correta.
2	400	O erro de BAD REQUEST será lançado quando você enviar valores inválidos nos parâmetros.
3	403	O erro de FORBIDDEN será lançado quando você utilizar chaves inválidas, chaves de autorização expiradas ou a URL invocadora não tiver permissão ou outros critérios de permissionamento.