Cookield

API Reference

Referência completa dos endpoints REST para gerenciar consentimentos, banners e configurações programaticamente.

Base URL

https://api.cookield.io

Todas as requisições devem ser feitas via HTTPS. A API retorna respostas em JSON.

Autenticação

A API utiliza Bearer tokens para autenticação. Obtenha um token através do endpoint de login e inclua-o no header de todas as requisições autenticadas:

Authorization: Bearer <your_access_token>

Os tokens expiram em 24 horas. Use o endpoint de refresh para obter um novo token sem exigir login novamente.

Auth

POST/auth/register

Cria uma nova conta de usuário.

Request Body

{
  "name": "João Silva",
  "email": "joao@empresa.com",
  "password": "securePassword123"
}

Response 201

{
  "user": {
    "id": "usr_abc123",
    "name": "João Silva",
    "email": "joao@empresa.com"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_xyz789..."
}
POST/auth/login

Autentica um usuário e retorna tokens de acesso.

Request Body

{
  "email": "joao@empresa.com",
  "password": "securePassword123"
}

Response 200

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_xyz789..."
}
POST/auth/refresh

Renova o access token usando um refresh token válido.

Request Body

{
  "refreshToken": "rt_xyz789..."
}

Response 200

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_newtoken..."
}

Banners

GET/organizations/:orgId/banners

Lista todos os banners da organização.

Response 200

{
  "data": [
    {
      "id": "ban_abc123",
      "domain": "meusite.com.br",
      "status": "active",
      "legislations": ["LGPD", "GDPR"],
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}
POST/organizations/:orgId/banners

Cria um novo banner para a organização.

Request Body

{
  "domain": "meusite.com.br",
  "legislations": ["LGPD"],
  "name": "Banner Principal"
}

Response 201

{
  "id": "ban_abc123",
  "domain": "meusite.com.br",
  "status": "draft",
  "scriptUrl": "https://api.cookield.io/banner/ban_abc123.js"
}
PATCH/organizations/:orgId/banners/:bannerId

Atualiza configurações de um banner existente.

Request Body

{
  "colors": {
    "primary": "#6366f1",
    "background": "#ffffff",
    "text": "#1f2937"
  },
  "position": "bottom"
}
DELETE/organizations/:orgId/banners/:bannerId

Remove um banner permanentemente.

Response 204

No content.

Consent

POST/v1/consent

Registra o consentimento de um visitante. Chamado automaticamente pelo script do banner.

Request Body

{
  "bannerId": "ban_abc123",
  "visitorId": "vis_xyz789",
  "categories": {
    "necessary": true,
    "analytics": true,
    "marketing": false,
    "functionality": true
  },
  "legislation": "LGPD"
}

Response 201

{
  "id": "con_abc123",
  "visitorId": "vis_xyz789",
  "timestamp": "2025-01-15T10:30:00Z",
  "status": "granted"
}
GET/v1/consent/:visitorId

Recupera o consentimento atual de um visitante.

Response 200

{
  "visitorId": "vis_xyz789",
  "categories": {
    "necessary": true,
    "analytics": true,
    "marketing": false,
    "functionality": true
  },
  "legislation": "LGPD",
  "updatedAt": "2025-01-15T10:30:00Z"
}
GET/v1/config/:bannerId

Retorna a configuração pública de um banner para renderização client-side.

Response 200

{
  "bannerId": "ban_abc123",
  "domain": "meusite.com.br",
  "colors": { "primary": "#6366f1" },
  "texts": { "title": "Usamos cookies", "accept": "Aceitar todos" },
  "categories": ["necessary", "analytics", "marketing"],
  "position": "bottom",
  "legislation": "LGPD"
}

Scanner

POST/organizations/:orgId/banners/:bannerId/scan

Inicia um scan automático do site para detectar cookies e scripts de terceiros.

Response 202

{
  "scanId": "scan_abc123",
  "status": "processing",
  "estimatedTime": 30
}

Metrics

GET/organizations/:orgId/metrics

Retorna métricas de consentimento da organização (pageviews, taxas de aceitação, etc.).

Query Parameters

?from=2025-01-01&to=2025-01-31&bannerId=ban_abc123

Response 200

{
  "pageviews": 45230,
  "consents": 38120,
  "acceptRate": 0.84,
  "rejectRate": 0.06,
  "customizeRate": 0.10,
  "byCategory": {
    "analytics": 0.78,
    "marketing": 0.52,
    "functionality": 0.91
  }
}

Documents

GET/organizations/:orgId/documents

Lista documentos legais (políticas de privacidade, termos de uso) da organização.

POST/organizations/:orgId/documents

Cria ou atualiza um documento legal.

Request Body

{
  "type": "privacy-policy",
  "title": "Política de Privacidade",
  "content": "...",
  "language": "pt-BR"
}

Webhooks

Configure webhooks para receber notificações em tempo real sobre eventos de consentimento.

Eventos disponíveis:

  • consent.created — Novo consentimento registrado
  • consent.updated — Consentimento alterado pelo visitante
  • consent.revoked — Consentimento revogado
  • banner.published — Banner publicado
  • scan.completed — Scan de cookies concluído

Payload Example

{
  "event": "consent.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "consentId": "con_abc123",
    "visitorId": "vis_xyz789",
    "bannerId": "ban_abc123",
    "categories": {
      "necessary": true,
      "analytics": true,
      "marketing": false
    }
  }
}

Rate Limits

A API possui limites de requisições por plano:

  • Free: 100 req/min
  • Pro: 1.000 req/min
  • Enterprise: 10.000 req/min

Headers de rate limit são incluídos em todas as respostas: X-RateLimit-Remaining, X-RateLimit-Reset.