API de Legal Cookies

La API de Legal Cookies permite analizar el cumplimiento de cookies de cualquier sitio web de forma programática. Está diseñada para equipos de desarrollo y compliance que necesitan integrar verificaciones automatizadas en sus flujos de trabajo, ya sea para auditorías periódicas, pipelines de CI/CD, o herramientas de monitorización continua.

A diferencia del análisis web manual, la API te permite ejecutar análisis de forma sistemática y obtener resultados estructurados que puedes procesar, almacenar y comparar a lo largo del tiempo. Cada análisis genera un reporte privado vinculado a tu cuenta, garantizando la confidencialidad de tus auditorías.

Qué problema resuelve

En muchas organizaciones, el cumplimiento de cookies se revisa solo cuando se publica una nueva web, cuando se cambia de CMP o cuando llega una auditoría externa. Ese enfoque deja huecos: los equipos de marketing pueden añadir etiquetas nuevas, una integración puede activar un pixel antes de tiempo, o una actualización del gestor de consentimiento puede cambiar el comportamiento real sin que nadie lo detecte hasta semanas después.

La API permite convertir esa revisión en un control continuo. En lugar de mirar una página una vez, puedes programar análisis recurrentes, comprobar entornos de preproducción antes de desplegar, revisar dominios críticos después de una campaña o guardar una serie histórica del score de cumplimiento. El objetivo no es sustituir al criterio legal, sino proporcionar evidencia técnica repetible para que desarrollo, privacidad y compliance hablen sobre datos concretos.

También es útil para consultoras, DPOs y equipos que gestionan múltiples dominios. Un portfolio de sitios puede auditarse con la misma metodología, los mismos umbrales y el mismo formato de salida. Eso reduce la variabilidad entre revisiones manuales y facilita priorizar: primero se corrigen las webs con tracking activo antes del consentimiento, después las que están en zona ámbar y requieren revisión de configuración.

Características principales

La API usa el mismo motor de análisis que la herramienta web, pero devuelve una respuesta compacta pensada para integración programática. El motor examina el comportamiento real del sitio web simulando una visita de usuario nuevo, capturando primero la precarga antes de cualquier decisión y, cuando el CMP es interactuable, comparando rechazo y aceptación.

Las principales funcionalidades incluyen:

• Análisis completo: El sistema detecta cookies, localStorage, sessionStorage, IndexedDB y peticiones a dominios de terceros que se ejecutan antes de obtener consentimiento del usuario. La evidencia avanzada añade scroll técnico previo al consentimiento y comparación representativa escritorio/móvil.

• Detección de CMP: Identifica automáticamente más de 20 plataformas de gestión de consentimiento (Cookiebot, OneTrust, CookieYes, etc.), lo que permite evaluar si el sitio tiene implementada una solución de gestión de cookies.

• Score de cumplimiento: Genera una puntuación de 5 a 100 en el algoritmo actual, basada en criterios GDPR, Directiva ePrivacy y LOPDGDD española. Esta puntuación facilita la priorización de esfuerzos de compliance.

• Reportes privados: A diferencia de los análisis públicos de la web, los análisis via API son privados por defecto y solo accesibles con tus credenciales.

• Autenticación segura: Utiliza HMAC-SHA256 para firmar cada petición, garantizando que solo tú puedes ejecutar análisis con tu cuenta y que las peticiones no pueden ser modificadas en tránsito.

Qué ocurre en cada análisis

Cada petición a /api/v1/analyze arranca una sesión limpia controlada en Chromium. El sistema crea una página nueva, limpia cookies/cache al finalizar y guarda la evidencia avanzada en navegaciones independientes, para aproximar la visita de un usuario nuevo y reducir contaminación entre pruebas.

Durante la carga se registran cookies visibles por JavaScript, cookies HttpOnly observadas en cabeceras Set-Cookie, elementos de localStorage y sessionStorage, requests de terceros, indicios de CMP y señales de tagging server-side. El sistema intenta capturar lo que aparece antes de aceptar o rechazar el banner porque esa precarga es una de las evidencias más relevantes en una auditoría de consentimiento. Después se guarda evidencia de cobertura: matriz before/reject/accept/reload, scroll limitado y comparación escritorio/móvil.

Después, los elementos se clasifican con una base local de patrones conocidos y, cuando hace falta, con el sistema de IA configurado para interpretar cookies y almacenamiento desconocido. Los dominios terceros no reconocidos se marcan con prudencia para revisión. El resultado final combina la evidencia detectada con el algoritmo de puntuación, generando una zona (green, yellow o red), un resumen y recomendaciones.

Qué puedes automatizar

La API encaja especialmente bien en flujos donde interesa tener una señal objetiva y periódica:

• Preproducción: analizar una URL antes de publicar cambios de etiquetas, CMP, scripts o plugins.
• CI/CD: fallar un pipeline si una web entra en zona roja o si aparecen cookies de marketing antes del consentimiento.
• Monitorización: revisar diariamente o semanalmente dominios críticos y registrar cambios de score.
• Consultoría: generar evidencias homogéneas para múltiples clientes o dominios.
• SaaS y herramientas internas: incorporar análisis de cookies dentro de plataformas propias de compliance o gobierno web.

La respuesta JSON está pensada para integrarse directamente: puedes guardar el reportId, mostrar el score, disparar alertas según zone, listar recomendaciones o abrir el informe completo con el código de recuperación devuelto.

Inicio rápido

El proceso para comenzar a usar la API consta de tres pasos sencillos. Una vez completados, podrás ejecutar análisis programáticos desde cualquier lenguaje de programación.

1. Solicita acceso

El primer paso es completar el formulario de registro con los datos de tu empresa y una descripción del caso de uso previsto. Esta información nos permite entender tus necesidades y configurar los límites adecuados para tu cuenta.

2. Recibe credenciales

Una vez aprobada tu solicitud (normalmente en 24-48 horas), recibirás por email dos credenciales que necesitarás para autenticar tus peticiones:

• API Key: Es el identificador público de tu cuenta, con formato lc_pk_.... Este valor se incluye en cada petición y no es secreto.

• API Secret: Es la clave privada que usarás para firmar tus peticiones. Se muestra una única vez en el momento de la aprobación, así que guárdala en un lugar seguro. Si la pierdes, podrás regenerar unas credenciales nuevas desde el panel de administración.

3. Integra

Con tus credenciales en mano, puedes comenzar a integrar la API en tu sistema. La guía de autenticación explica en detalle cómo calcular la firma HMAC, y la sección de ejemplos de código incluye implementaciones completas en Node.js, Python, PHP, Rust, C# y cURL que puedes usar como punto de partida.

Endpoint principal

La API v1 expone un único endpoint para análisis de URLs. Este diseño simplificado facilita la integración y reduce la curva de aprendizaje.

El endpoint acepta una URL pública (HTTP o HTTPS) y devuelve un análisis completo del comportamiento de cookies del sitio. El tiempo de respuesta típico es de 5 a 15 segundos, dependiendo de la complejidad del sitio analizado.

Seguridad y privacidad

La autenticación HMAC evita enviar el API Secret en claro. Cada request se firma usando el método HTTP, el path exacto del endpoint, el timestamp y el hash SHA256 del body. Si alguien modifica el body, cambia el path o reutiliza una firma fuera de la ventana temporal permitida, la verificación falla.

Las URLs analizadas mediante API generan informes privados por defecto. Eso significa que no se publican en el listado público de informes y quedan asociadas al cliente API que ejecutó el análisis. El código de recuperación permite volver a consultar el informe, pero debe tratarse como un enlace privado: quien lo conozca puede acceder a ese resultado.

La API también valida las URLs antes de analizarlas para reducir riesgo SSRF: se rechazan protocolos no permitidos, localhost, IPs privadas, hostnames internos y destinos que resuelvan a rangos no públicos. Esta validación es relevante porque el servicio ejecuta un navegador real contra la URL solicitada.

Límites de uso

Cada cuenta tiene límites configurados para garantizar un uso justo del servicio. Los límites por defecto son suficientes para la mayoría de casos de uso de auditoría y monitorización.

Estos límites se aplican de forma acumulativa: una petición consume una unidad de cada contador. Los contadores de minuto, hora y día se reinician automáticamente en sus respectivos intervalos. El contador total representa el límite de tu plan.

Si tu caso de uso requiere límites mayores, contacta con nosotros describiendo tus necesidades. Podemos ajustar los límites según el volumen de análisis que necesites realizar.

Estructura de respuesta

Cada análisis exitoso devuelve un objeto JSON con información detallada sobre el estado de cumplimiento del sitio. La respuesta está diseñada para ser fácil de procesar programáticamente mientras proporciona toda la información necesaria para evaluar el cumplimiento.

{
  "success": true,
  "data": {
    "reportId": "abc123def456",
    "hash": "codigo_recuperacion_privado",
    "score": 75,
    "zone": "yellow",
    "verdict": "Cumplimiento parcial",
    "verdictReason": "Se detectaron 3 cookies que requieren consentimiento...",
    "summary": "El sitio presenta un nivel de cumplimiento parcial...",
    "recommendations": [
      "Configurar el CMP para bloquear cookies hasta obtener consentimiento",
      "Revisar las cookies de terceros identificadas como problemáticas"
    ],
    "stats": {
      "totalCookies": 15,
      "problematicCookies": 3,
      "exemptCookies": 5,
      "totalStorageItems": 2,
      "totalThirdPartyRequests": 8,
      "cmpDetected": "Cookiebot",
      "analysisDurationMs": 4500
    }
  }
}

El campo score proporciona una métrica numérica rápida, mientras que zone indica el nivel de riesgo (green, yellow, red). Las recommendations ofrecen pasos concretos para mejorar el cumplimiento, y stats contiene las métricas detalladas del análisis.

Siguientes pasos

Para comenzar a usar la API, te recomendamos seguir este orden de lectura: