API REST

La API REST te permite automatizar todo lo que puedes hacer en el panel: añadir dominios, lanzar escaneos, buscar y exportar registros de consentimiento y recibir webhooks cuando algo cambia. Está disponible en los planes Pro y Enterprise.

Autenticación

Crea una clave de API en Settings → API keys. Cada clave pertenece a un único espacio de trabajo y es de solo lectura o de lectura y escritura. Envía la clave como token bearer:

curl https://api.cookiesh.eu/v1/domains \
  -H "Authorization: Bearer ck_sk_live_..."

Las claves secretas empiezan por ck_sk_. No las uses nunca en código del navegador. La etiqueta script solo necesita tu Site ID público.

Todas las solicitudes usan HTTPS y JSON. La URL base es https://api.cookiesh.eu/v1. Las marcas de tiempo son cadenas ISO 8601 en UTC.

Endpoints

Método	Ruta	Descripción
GET	/domains	Lista los dominios del espacio de trabajo
POST	/domains	Añade un dominio
GET	/domains/{id}	Obtiene un dominio y su configuración
DELETE	/domains/{id}	Elimina un dominio
POST	/domains/{id}/scans	Lanza un escaneo de cookies
GET	/domains/{id}/scans/{scan_id}	Obtiene el estado y los resultados de un escaneo
GET	/domains/{id}/cookies	Lista las cookies y los rastreadores clasificados
GET	/consents	Busca registros de consentimiento
GET	/consents/{consent_id}	Obtiene un registro de consentimiento con su prueba de la cadena de hashes
POST	/exports	Inicia una exportación de registros de consentimiento en CSV o JSON
GET	/exports/{id}	Obtiene el estado de una exportación y su URL de descarga
DELETE	/subjects/{user_id}	Elimina todos los registros de consentimiento vinculados a un ID de usuario

Ejemplo: buscar los registros de consentimiento de un visitante.

curl "https://api.cookiesh.eu/v1/consents?domain_id=dom_29xk&consent_id=cns_8Hq2Lw" \
  -H "Authorization: Bearer ck_sk_live_..."

{
  "data": [
    {
      "id": "cns_8Hq2Lw",
      "domain_id": "dom_29xk",
      "created_at": "2026-10-12T09:41:07Z",
      "region": "DE",
      "method": "banner",
      "banner_version": "v14",
      "categories": { "necessary": true, "preferences": false, "analytics": true, "marketing": false },
      "hash": "9f2c…e71a"
    }
  ],
  "next_cursor": null
}

Paginación

Los endpoints de listado devuelven hasta 100 elementos. Pasa limit para pedir menos. Si hay más resultados, la respuesta incluye un next_cursor. Devuélvelo como cursor para obtener la página siguiente. Los cursores son válidos durante 24 horas.

Errores

Los errores usan los códigos de estado HTTP estándar y un cuerpo con formato uniforme:

{
  "error": {
    "type": "invalid_request",
    "message": "domain_id is required",
    "request_id": "req_4Kd92"
  }
}

Estado	Significado
400	La solicitud no es válida. El mensaje explica el motivo.
401	Falta la clave de API o no es válida.
403	La clave es de solo lectura o tu plan no incluye esta función.
404	El recurso no existe en este espacio de trabajo.
429	Has alcanzado el límite de solicitudes. Vuelve a intentarlo tras los segundos indicados en Retry-After.
5xx	Algo ha fallado por nuestra parte. Vuelve a intentarlo con espera exponencial.

Incluye el request_id cuando te pongas en contacto con soporte.

Límites de solicitudes

Los espacios de trabajo Pro pueden hacer 600 solicitudes por minuto, y los Enterprise, 3.000. Cada respuesta incluye las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Las exportaciones no cuentan para el límite mientras se ejecutan.

Webhooks

Añade un endpoint en Settings → Webhooks y elige los eventos que quieres recibir:

Evento	Se envía cuando
consent.created	Un visitante guarda una nueva elección
consent.updated	Un visitante cambia una elección anterior
scan.completed	Termina un escaneo de cookies
scan.new_items	Un escaneo encuentra cookies o rastreadores que requieren revisión
usage.threshold	El espacio de trabajo alcanza el 80 % o el 100 % de sus registros de consentimiento mensuales

Cada entrega es un POST con un cuerpo JSON y una cabecera Cookiesh-Signature. La cabecera contiene una marca de tiempo y una firma HMAC-SHA256 de timestamp.body, generada con el secreto de firma de tu endpoint. Verifícala antes de fiarte de la carga útil:

import crypto from 'node:crypto';

export function verify(rawBody: string, header: string, secret: string): boolean {
  const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // rechaza las entregas antiguas
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Responde con un estado 2xx en menos de 10 segundos. Las entregas fallidas se reintentan con espera exponencial durante un máximo de 24 horas. Un mismo evento puede llegar más de una vez, así que usa su id para descartar duplicados.