API's de consentimentos

As API’s permite formatos de comunicação para realizar integrações entre sistemas. Elas podem ser ser utilizadas para, por exemplo:

Realizar atualizações de consentimentos de formas síncronas entre dois sites/sistemas.
Extrair a base de dados de consentimentos.

Essa documentação tem como objetivo dar um contexto maior sobre as API’s de consentimento da Privacy Tools, com maiores especificações técnicas e considerações de uso, é suposto que a construção de código e demais entendimentos de ferramentas e protocolos de ampla utilização já seja de conhecimento do time que estará envolvido com qualquer trabalho relacionado as APi’s.

Método de autenticação:

Para consumo das APi’s de consentimento é necessario primeiramente a criação de um Usuario de API na plataforma, onde será disponibilizado um conjunto de credenciais para consumo do endpoint para criação do token de autorização.

Para os demais endpoint disponibilizados em nosso swagger sendo utilizado o protocolo de autorização OAuth2, utilizando o access_token junto ao token_type fornecido no response do endpoint /oauth/token, que está no link indicado anteriormente.

Base URL

A url base do consumo irá depender em qual ambiente o usuario de API foi criado, em ambientes de produção a URL será:

https://dpo.privacytools.com.br/external_api_v2/

Já em demo, será substituído o começo da URL pelo ambiente:

https://demo.privacytools.com.br/external_api_v2/

Principais endpoints:

Método: POST

Realiza a criação de um Titular de dados, contendo informações de cadastro como email, documento, telefone, entre outros, podendo ser também criado com um status de consentimento atrelado a uma finalidade.

Documentação completa: API - consent/import

Método: GET

Retorna os titulares de dados com consentimentos na lista de titulares. O retorno é feito por paginação (offset), que é passado no header da requisição.

Documentação completa: API /consent/find e consent/find/fixed

Método: GET

Realiza a validação se um titular de dados consentiu ou não uma finalidade, retornando o status baseado no estado de consentimento do usuario mais recente dessa finalidade.

Documentação completa: API - /consent/check/{templateHash}/{userHash}

Ainda é possivel ver a lista completa de API’s de consentimento em nosso swagger na aba: https://dpo.privacytools.com.br/external_api_v2/swagger-ui.html#/external-consent-controller

Realizando vinculo com uma finalidade (templateHash)

Para a maioria das API’s de consentimento é feito o vinculo com uma finalidade utilizando o templateHash, sendo esse um hash único para identificar a finalidade a qual a API deve se comunicar.

A coleta dessa informação pode ser feita de duas formas:

Com acesso a plataforma:

Entrando na plataforma, siga o caminho Privacidade > Finalidades > +Finalidades, assim você poderá acessar a lista de finalidades criadas em um grupo de findardes, onde você pode copiar o Hash de registro.

Com um Usuario de API:

Você também pode realizar o consumo de duas API’s para ter a lista de grupos de consentimentos, e com a informação de groupId consumir a API para retornar as informações da finalidade desse grupo, contendo o hash de registro:

/consent/manage/groups/{language} - Retorna a lista de grupos de consentimento, com base na linguagem. Constando atributo groupId.

ID de cada linguagen:

Cada linguagem possui um id, no consumo da API, é enviado no header apenas o id da linguagem:

1 - Português

2 - Inglês

3 - Espanhol

4 - Russo

5 - Alemão

6 - Francês

7 - Italiano

8 - Polonês

9 - Mandarim

10 - Árabe

11 - Holandês

/consent/manage/purpouses/{groupId} - Retorna a listagem de finalidades dentro de um grupo, cada uma contendo também seu Hash de registro