API: introducción

Esta sección documenta la superficie del API de CookyCMP orientada a clientes: la configuración del banner, el registro de consentimiento, la declaración de cookies y el export de evidencia.

Base URL

https://api.cookycmp.com

Todos los endpoints documentados viven bajo el prefijo /v1. Las respuestas son JSON (application/json), salvo donde se indica lo contrario (CSV, HTML embebible).

Endpoints públicos (sin autenticación)

Los consumen el banner y el widget de declaración directamente desde el navegador del visitante:

Endpoint	Descripción
GET /v1/config/:siteId	Configuración del banner de un sitio: vendors activos, textos, tema, posición, idioma, versión de política y configuración de jurisdicción. Valida el Origin del request contra el dominio registrado del sitio.
POST /v1/consent	Registra un evento de consentimiento. Ver Consentimiento.
GET /v1/declaration/:siteId	Declaración de cookies en JSON. Ver Declaración de cookies.
GET /v1/declaration/:siteId/embed	Declaración de cookies como HTML autocontenido para iframe.

En estos endpoints el sitio se identifica por su Site ID (UUID); ningún endpoint público expone identificadores internos del tenant.

Autenticación

API keys de tenant (ck_live_…)

Para integraciones de servidor (por ejemplo, la Connector API que usa el plugin de WordPress), CookyCMP emite API keys con el prefijo ck_live_. Se crean y revocan desde el dashboard (rol admin) y se envían en el header Authorization:

Authorization: Bearer ck_live_XXXXXXXXXXXX

Cada key tiene scopes que limitan qué puede hacer (por ejemplo connect:config para configurar el sitio conectado y connect:usage para leer el uso del plan). El secreto se muestra una sola vez al crearla — CookyCMP guarda solo un hash. Una key revocada o vencida responde 401.

Sesión del dashboard (token JWT)

Los endpoints de gestión — como el export de consentimientos — exigen un token de sesión del dashboard (JWT) con el rol adecuado, enviado también como Authorization: Bearer …. Estos endpoints están pensados para usarse desde el dashboard; esta documentación cubre solo los relevantes para extraer evidencia.

Formato de errores

Los errores devuelven un objeto JSON con un campo error y el código HTTP correspondiente:

{ "error": "site_not_found" }

Código	Significado
400	Request inválido (validación de esquema o parámetros).
401	Falta autenticación o la credencial es inválida/revocada.
403	Autenticado pero sin permiso (rol, scope, origen no permitido o sitio no verificado).
404	Recurso inexistente o inactivo.
422	El request es válido pero viola una regla de negocio (p. ej., consentimiento de datos sensibles sin confirmación expresa).
429	Rate limit superado. Incluye el header Retry-After y, según el endpoint, X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset.
500	Error interno. La respuesta no incluye detalles técnicos.

Algunos endpoints devuelven códigos de error legibles por máquina en el campo error (site_not_found, rate_limit_exceeded, origin_not_allowed, site_not_verified, …); tratalos como identificadores estables, no como texto para mostrar al usuario final.