API Pública

Documentação completa da API REST da Consentio para programadores

Visão geral

A API Pública da Consentio disponibiliza acesso programático aos seus dados de consentimento. Pode utilizá-la para:

Integração com as suas próprias ferramentas de análise
Exportação de dados para relatórios
Automatização da gestão do website
Criação de dashboards personalizados

Importante: A API Pública está disponível apenas no plano Pro. O plano Free não tem acesso à API.

Autenticação

A API utiliza autenticação por chave de API. Envie a chave no cabeçalho Authorization:

Cabeçalho HTTP

Authorization: ApiKey sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Obter uma chave de API

Inicie sessão no painel da Consentio
Aceda a Definições → Chaves de API
Clique em Gerar nova chave
Copie a chave e guarde-a em local seguro

Segurança: Nunca partilhe a sua chave de API nem a guarde em repositórios públicos. A chave dá acesso a todos os dados da sua conta.

URL base

Envie todos os pedidos de API para:

URL

https://consentio.cz/api/v1

Limitação de taxa

A API tem um limite no número de pedidos por hora:

Plano	Pedidos/hora
Pro	1.000

A resposta inclui cabeçalhos com informação sobre o limite de taxa:

Cabeçalhos de resposta

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1704067200

Formato de resposta

Todas as respostas estão em formato JSON com uma estrutura consistente:

Resposta com sucesso

JSON

{
  "success": true,
  "data": { ... }
}

Resposta de erro

JSON

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}

Endpoints

GET /websites

Devolve uma lista de todos os websites atribuídos à sua conta.

Exemplo de pedido

curl

curl -X GET "https://consentio.cz/api/v1/websites" \
  -H "Authorization: ApiKey sk_live_xxx"

Exemplo de resposta

JSON

{
  "success": true,
  "data": [
    {
      "id": "clx1234567890",
      "name": "My e-shop",
      "domain": "my-eshop.com",
      "description": "Main e-shop",
      "status": "active",
      "cookieCount": 15,
      "consentCount": 1250,
      "consentRate": 78,
      "viewsThisMonth": 450,
      "lastScanAt": "2025-01-15T10:30:00.000Z",
      "createdAt": "2024-06-01T08:00:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

GET /websites/:id

Devolve os detalhes de um website específico, incluindo as definições.

Parâmetros

Parâmetro	Tipo	Descrição
`id`	string	ID do website (no URL)

Exemplo de pedido

curl

curl -X GET "https://consentio.cz/api/v1/websites/clx1234567890" \
  -H "Authorization: ApiKey sk_live_xxx"

GET /websites/:id/cookies

Devolve uma lista dos cookies detetados no website.

Exemplo de pedido

curl

curl -X GET "https://consentio.cz/api/v1/websites/clx1234567890/cookies" \
  -H "Authorization: ApiKey sk_live_xxx"

GET /analytics

Devolve dados analíticos de um website - estatísticas de consentimento, geografia, dispositivos e tendências.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`websiteId`	string	Sim	ID do website
`period`	string	Não	Período: 7d, 30d, 90d, all (padrão: 30d)

Exemplo de pedido

curl

curl -X GET "https://consentio.cz/api/v1/analytics?websiteId=clx123&period=30d" \
  -H "Authorization: ApiKey sk_live_xxx"

Exemplo de resposta

JSON

{
  "success": true,
  "data": {
    "summary": {
      "totalViews": 1250,
      "consentRate": 78.5,
      "acceptedCount": 850,
      "rejectedCount": 275,
      "customCount": 125,
      "uniqueVisitors": 980,
      "totalImpressions": 2500
    },
    "consentBreakdown": {
      "acceptAll": 68,
      "rejectAll": 22,
      "custom": 10
    },
    "categoryConsent": {
      "necessary": 100,
      "analytics": 72,
      "marketing": 45,
      "functionality": 58
    },
    "geographic": [
      {
        "country": "Czechia",
        "countryCode": "CZ",
        "flag": "🇨🇿",
        "count": 850,
        "percentage": 68
      }
    ],
    "devices": {
      "desktop": 55,
      "mobile": 40,
      "tablet": 5
    },
    "trend": [
      {
        "date": "2025-01-01",
        "views": 45,
        "accepted": 35,
        "rejected": 10
      }
    ],
    "utmBreakdown": {
      "sources": [...],
      "mediums": [...],
      "campaigns": [...]
    }
  }
}

GET /consents

Devolve uma lista de consentimentos individuais com paginação.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`websiteId`	string	Sim	ID do website
`startDate`	ISO 8601	Não	Data de início (ex.: 2025-01-01)
`endDate`	ISO 8601	Não	Data de fim
`limit`	number	Não	Número de registos (padrão: 100, máx.: 1000)
`offset`	number	Não	Registos a saltar (padrão: 0)

Exemplo de pedido

curl

curl -X GET "https://consentio.cz/api/v1/consents?websiteId=clx123&limit=50&offset=0" \
  -H "Authorization: ApiKey sk_live_xxx"

Exemplo de resposta

JSON

{
  "success": true,
  "data": [
    {
      "id": "consent_abc123",
      "visitorId": "v_xyz789",
      "action": "ACCEPT_ALL",
      "categories": {
        "necessary": true,
        "analytics": true,
        "marketing": true,
        "functionality": true
      },
      "ipCountry": "CZ",
      "device": "desktop",
      "utmSource": "google",
      "utmMedium": "cpc",
      "utmCampaign": "brand",
      "createdAt": "2025-01-15T14:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1250,
    "hasMore": true
  }
}

POST /consents/export

Exporta os consentimentos para um ficheiro CSV ou JSON.

Parâmetros do corpo do pedido

Parâmetro	Tipo	Obrigatório	Descrição
`websiteId`	string	Sim	ID do website
`startDate`	ISO 8601	Não	Data de início
`endDate`	ISO 8601	Não	Data de fim
`format`	string	Não	"csv" ou "json" (padrão: json)

Exemplo de pedido

curl

curl -X POST "https://consentio.cz/api/v1/consents/export" \
  -H "Authorization: ApiKey sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "websiteId": "clx1234567890",
    "startDate": "2025-01-01",
    "endDate": "2025-01-31",
    "format": "csv"
  }' \
  -o consents.csv

GET /account/usage

Devolve a utilização atual da conta face aos limites do plano.

Exemplo de pedido

curl

curl -X GET "https://consentio.cz/api/v1/account/usage" \
  -H "Authorization: ApiKey sk_live_xxx"

Exemplo de resposta

JSON

{
  "success": true,
  "data": {
    "plan": "PRO",
    "websites": {
      "used": 3,
      "limit": 15
    },
    "pageviews": {
      "used": 45000,
      "limit": 250000,
      "periodStart": "2025-01-01T00:00:00.000Z",
      "periodEnd": "2025-01-31T23:59:59.999Z"
    },
    "analyticsRetention": "unlimited",
    "scanInterval": "1 day",
    "apiRequests": {
      "used": 150,
      "limit": 1000,
      "resetAt": "2025-01-15T15:00:00.000Z"
    }
  }
}

Códigos de erro

Estado HTTP	Código	Descrição
400	`MISSING_WEBSITE_ID`	O parâmetro obrigatório websiteId está em falta
400	`INVALID_FORMAT`	Formato de exportação inválido
401	`UNAUTHORIZED`	Chave de API em falta ou inválida
403	`API_ACCESS_DENIED`	O seu plano não tem acesso à API
404	`WEBSITE_NOT_FOUND`	Website não encontrado ou acesso negado
429	`RATE_LIMIT_EXCEEDED`	Limite de pedidos excedido
500	`INTERNAL_ERROR`	Erro interno do servidor

SDKs e bibliotecas

Estamos a preparar SDKs oficiais para as linguagens mais populares:

JavaScript/TypeScript (npm)
Python (pip)
PHP (composer)

Dica: Quer ser notificado quando os SDKs forem lançados? Siga as nossas novidades ou contacte-nos em [email protected].

Idiomas