Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.haldenhub.com/llms.txt

Use this file to discover all available pages before exploring further.

Esta página descreve os endpoints /api/v1/consents para integração server-to-server ou uso autenticado pelo dashboard. Eles são distintos do fluxo público do banner (POST /api/v1/public/consent), que usa o header X-Site-Token. Para obter e usar uma API Key, consulte API Key.

​
Autenticação

Envie uma das opções:
  • API Key: Authorization: Bearer sk-... (recomendado para backends).
  • Sessão do dashboard: cookie JWT emitido pelo login (mesmas rotas).
As rotas abaixo aceitam API Key ou sessão do dashboard (cookie). Somente chamadas com API Key (Authorization: Bearer sk-...) consomem a cota mensal do plano; o uso pelo painel com JWT não incrementa o contador (veja API Key).

​
Endpoints

MétodoCaminhoDescrição
POST/api/v1/consentsCria um registro de consentimento para um site_id seu.
GET/api/v1/consentsLista com filtros e paginação por cursor.
GET/api/v1/consents/{id}Detalhe de um consentimento.
PUT/api/v1/consents/{id}Atualiza aceite e/ou preferências (alterações auditadas).
DELETE/api/v1/consents/{id}Exclusão lógica (LGPD / direito ao esquecimento).
GET/api/v1/consents/{id}/historyTrilha de auditoria do consentimento.
Referência detalhada (schemas, códigos de erro): aba API Reference nesta documentação — ficheiro openapi.yaml gerado a partir do Swag no repositório cosmos (make openapi-docs), tags Consents e API Key.

​
Criar consentimento (exemplo)

Corpo mínimo: site_id obrigatório; demais campos opcionais conforme seu caso. 
POST /api/v1/consents HTTP/1.1
Host: www.haldenhub.com.br
Authorization: Bearer sk-...
Content-Type: application/json

{
  "site_id": "00000000-0000-0000-0000-000000000000",
  "subject_id": "hash-do-titular",
  "consent_id": "id-estavel-no-seu-sistema",
  "accepted": true,
  "preferences": { "analytics": true, "marketing": false },
  "policy_version": 3,
  "ip_address": "203.0.113.10",
  "user_agent": "MeuBackend/1.0"
}
Resposta 201: objeto ConsentDTO com id, created_at, policy_version, etc.

​
Listagem e filtros

GET /api/v1/consents aceita query params:
  • site_id, subject_id, consent_id
  • accepted (true / false)
  • from, to (date-time ISO)
  • cursor, limit (padrão 50, máximo 100)
Use next_cursor da resposta para a próxima página.

​
Não confundir com o banner no site

IntegraçãoEndpointAutenticação
Snippet no navegadorPOST /api/v1/public/consentX-Site-Token (token do site)
Backend / automaçãoPOST /api/v1/consentsJWT ou Bearer sk-...

​
Erros frequentes

Os corpos de erro seguem o schema Error (error + message). Em especial:
  • unauthorized — API Key inválida ou revogada.
  • quota_exceeded — cota mensal da API esgotada (429).
  • not_found — consentimento ou site não encontrado para o usuário autenticado.
  • invalid_request — corpo ou query inválidos (ex.: cursor malformado).

Dúvidas? suporte@haldenhub.com.br