API Referencia

Integra con la Plataforma de Gestión de Consentimiento de Conzent. Estos puntos finales alimentan el banner de consentimiento, la segmentación geográfica, el registro de auditoría de consentimiento y el escaneo de cookies.

Todos los puntos finales son relativos a tu instancia de Conzent autoalojada. Reemplaza la URL base con tu dominio real.

Autenticación

La mayoría de los puntos finales son públicos — se llaman desde el script del banner de consentimiento que se ejecuta en los navegadores de tus visitantes.

Los puntos finales que aceptan datos utilizan una Clave de Sitio para identificar a qué sitio pertenece la solicitud. Encuentra tu clave de sitio en el panel de control de Conzent bajo Sitios.

Formato de Respuesta

Las respuestas de la API utilizan dos formatos dependiendo del punto final:

Respuesta Estándar

Usado por Verificación de Salud y Webhook de Escaneo.

{
  "success": true,
  "data": {
    "status": "ok"
  }
}

Respuesta Ligera

Usado por puntos finales de beacon (Vista de Página, Consentimiento, Datos de Escaneo) para una sobrecarga mínima.

{
  "status": "ok"
}

Verificación de Salud

Devuelve el estado de salud de la aplicación y los servicios de respaldo. Úsalo para monitoreo, verificaciones de balanceador de carga y sondas de salud de Docker.

Respuesta

{
  "success": true,
  "data": {
    "status": "ok",
    "services": {
      "database": true,
      "redis": true
    },
    "environment": "producción",
    "timestamp": "2026-03-16T12:00:00+00:00"
  }
}

{
  "success": true,
  "data": {
    "status": "degradado",
    "services": {
      "database": true,
      "redis": false
    }
  }
}

Ejemplo

curl https://your-instance.example.com/health

Geolocalización

Devuelve el código de país del visitante y el estado de membresía en la UE. Usado por el script de consentimiento para aplicar regulaciones geográficas (GDPR, CCPA).

Campos de Respuesta

Respuesta

{
  "country": "dk",
  "in_eu": true
}

Ejemplo

curl https://your-instance.example.com/api/v1/geo_ip

Beacon de Vista de Página

Registra eventos de vista de página y carga de banner. Enviado a través de navigator.sendBeacon() como multipart/form-data. Incrementa el contador diario de vistas de página y almacena observaciones de cookies para procesamiento asíncrono.

Cuerpo de Solicitud multipart/form-data

Respuesta

{
  "status": "ok"
}

Ejemplo

curl -X POST https://your-instance.example.com/api/v1/log \
  -F "key=YOUR_WEBSITE_KEY" \
  -F "request_type=banner_load" \
  -F "log_time=$(date +%s)"

Registro de Consentimiento

Registra la auditoría de consentimiento del GDPR cuando un visitante acepta, rechaza o personaliza el consentimiento. Este es el punto final principal de cumplimiento.

Cuerpo de Solicitud multipart/form-data

Respuesta

{
  "status": "ok"
}

Ejemplo

curl -X POST https://your-instance.example.com/api/v1/consent \
  -F "key=YOUR_WEBSITE_KEY" \
  -F "conzent_id=a1b2c3d4e5f6..." \
  -F 'log=[{"category":"analytics","consented":true}]' \
  -F "consented_domain=example.com" \
  -F "language=en" \
  -F "country=dk"

Beacon de Datos de Escaneo

Recibe datos de escaneo de cookies del lado del cliente. El script de consentimiento detecta cookies en el navegador del visitante y las informa para categorización automática. Los datos se almacenan en Redis y se procesan de manera asíncrona.

Cuerpo de Solicitud multipart/form-data

Estructura del Payload

{
  "scan_id": 123,
  "action": "runscan",
  "scan_url": "https://example.com/",
  "consent_phase": "pre_consent",
  "data": {
    "cookies": [
      { "name": "_ga", "domain": ".example.com" }
    ]
  }
}

Respuesta

{
  "status": "ok"
}

Ejemplo

curl -X POST https://your-instance.example.com/api/v1/scan_data \
  -F "key=YOUR_WEBSITE_KEY" \
  -F 'payload={"scan_id":123,"action":"runscan","scan_url":"https://example.com/"}'

Webhook de Escáner

Recibe resultados de escaneo de servidores de escáner externos cuando se completa un escaneo de cookies. Autenticado a través del encabezado X-Api-Key que coincide con la SCANNER_WEBHOOK_SECRET variable de entorno.

Encabezados

Cuerpo de Solicitud application/json

Respuesta

{
  "success": true,
  "data": {
    "status": "processed"
  }
}

Error

{
  "success": false,
  "error": "No autorizado"
}

Ejemplo

curl -X POST https://your-instance.example.com/api/v1/scan-webhook \
  -H "X-Api-Key: YOUR_SCANNER_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "webhook",
    "scan_id": 456,
    "scan_url": "https://example.com/",
    "data": {
      "cookies": [
        {"name": "_ga", "domain": ".example.com", "category": "analytics"}
      ]
    }
  }'