Cookies y tu integración de consentimiento

Si ya integraste el módulo de consentimiento, Cookies usa la misma Entity. Reutiliza tu user_reference para que las decisiones de cookies y los consentimientos previos apunten al mismo sujeto.

Esta guía explica cómo se conecta Cookies con tu integración existente, qué recursos materializa Soyio y cómo enterarte de cada decisión desde tu backend.

Una sola Entity para cookies y consentimiento

Al emitir un token de sesión, Soyio usa el mismo lookup que consent_actions: busca o crea la Entity por user_reference dentro de tu empresa.

Si tu integración de consentimiento ya usa user_reference, envía el mismo valor. Soyio reutiliza esa Entity.
Si integraste solo con entity_id, esa Entity quedó con user_reference: nil y el lookup no la encuentra. Soyio crea un sujeto nuevo y las decisiones de cookies quedan separadas de los consentimientos previos.

Envía siempre el mismo user_reference interno y estable para mantener un único sujeto. Revisa Sujetos de datos y Captura de consentimiento para alinear ambos flujos.

La Entity nace al emitir el token

Soyio crea o asocia la Entity en la misma llamada que emite el token, para sync_preferences y claim_visitor, aunque el visitante nunca registre una decisión. Cada login que solicita un token toca esa Entity.

En claim_visitor, Soyio además crea una Entity de navegador con referencia cookie:<csite_token>:<visitor_uuid> cuando hay historial anónimo que reclamar. La fusiona al sujeto canónico durante la atribución. Es un artefacto interno de la cadena de merge: no lo administres, pero ten presente que sus acuerdos transitorios pueden emitir eventos agreement.* antes de la fusión.

Sujetos fusionados

Si la Entity está fusionada a una Identity, la decisión se atribuye a la Identity: subject_type es Identity y subject_id trae el token de la Identity.

Soyio resuelve el sujeto canónico al emitir el token, al usarlo y al materializar la decisión. Una fusión posterior no deja decisiones colgando en la Entity antigua.

subject_merge_id aparece solo en decisiones atribuidas por claim_visitor. Las decisiones capturadas directamente no lo incluyen.

Qué materializa Soyio

Al atribuir la decisión, Soyio la registra como nueva versión del Agreement vigente del sujeto. No crea un Agreement aparte.

version_source apunta a la CookieConsentAction que originó la versión. En claim_visitor, la reconciliación final puede usar el SubjectMerge de la fusión como version_source
Una DataPermission por cada categoría aceptada
Evidence con la decisión en evidence.cookie_consent_action

Cada permiso de cookies tiene esta forma:

Campo	Valor
`data_category`	`user.device.cookie`
`data_label`	`cookie.<categoría>`
`data_use`	`<categoría>`
`data_subject`	`visitor`
`scope_type`	`cookie_site`
`scope_id`	`csite_TU_TOKEN`
`scope_version`	`1`
`expires_at`	Del estado de consentimiento resuelto, no necesariamente de la decisión que originó esta versión: ante decisiones simultáneas se toma el más restrictivo

Una decisión nueva reemplaza solo los permisos con scope_type: cookie_site del mismo scope_id. Los demás permisos del acuerdo se conservan. Revisa Acuerdos y permisos para entender el versionado.

Entérate desde tu backend

No existe un evento cookie_* ni consent_action.created para cookies. La decisión de cookies viaja dentro de los eventos de acuerdo:

agreement.created en la primera versión del sujeto
agreement.updated en las versiones siguientes

Busca la decisión en payload.evidence.cookie_consent_action:

Recorte del payload
{
  "name": "agreement.updated",
  "payload": {
    "evidence": {
      "cookie_consent_action": {
        "action_id": "cconsact_1B2M2Y8AsgTpgAmY7PhCfg",
        "site_id": "csite_TU_TOKEN",
        "config_id": "cbcfg_1B2M2Y8AsgTpgAmY7PhCfg",
        "config_version": 3,
        "decision": "custom",
        "accepted_categories": ["essential", "analytics"],
        "rejected_categories": ["functional", "marketing", "personalize"],
        "visitor_uuid": "b0e2...",
        "expires_at": "2027-07-27T18:15:00Z",
        "receipt_integrity_hash": "9f849a99e7a4df9f122792cd04cacb56d6983642762fc96e6ed08c1d875a4c509b927dca4d2a1a9627f4c0d738c3afa01481efe37ab6a2386eadb85b29e4337f"
      }
    }
  }
}

payload.evidence.cookie_consent_action lleva la decisión cuando la versión del acuerdo proviene de una decisión de cookies. Es la vía principal para enterarte de una decisión atribuida, aunque la reconciliación final de un claim_visitor puede emitir un agreement.updated sin ese bloque. Sigue también por subject_id, entity_id o subject_merge_id si necesitas reconstruir la cadena completa.

Revisa los eventos agreement.created y agreement.updated, o parte por la guía de Webhooks.

Solo recibes eventos de decisiones atribuidas a un sujeto. Para las decisiones anónimas, consulta con polling GET /cookie_consent_actions y filtra por cookie_site_id, cookie_banner_config_id, cookie_banner_config_version, entity_id, subject_id o global_search, más rangos de fecha en where.

Cuando la materialización falla

Cada decisión expone materialization_status y, cuando falla, failure_code:

Estado	Significado
`pending`	Soyio está procesando la decisión
`completed`	Agreement, Evidence y perfil interno quedaron creados
`failed`	La materialización falló; revisa `failure_code`
`not_applicable`	Decisión anónima, sin atribución

La captura identificada reintenta hasta 5 veces en background. claim_visitor no reintenta y no existe un proceso automático de recuperación.

Detecta las decisiones failed con polling o exportaciones. Registrar una decisión nueva no recupera la fallida: se materializa solo la CookieConsentAction nueva y el recibo anterior sigue failed.

Para reintentar la fallida hay que volver a materializar esa misma decisión. La captura identificada lo hace en su reintento de background; para el historial anónimo, un claim_visitor nuevo reintenta las decisiones fallidas. No esperes un reintento automático para las decisiones atribuidas por claim_visitor.

Exporta las decisiones

Solicita una exportación con resource: "cookie_consent_actions":

curl -X POST \
  https://app.soyio.id/api/v1/exports \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "cookie_consent_actions",
    "output_format": "json",
    "where": "{\"cookie_site_id\":{\"=\":\"csite_TU_TOKEN\"}}"
  }'

La API responde 202 Accepted y notifica con export.completed cuando el archivo está listo. Necesitas los permisos exports.api.write y consent.api.cookie_actions.read (o consent.api.read). Revisa Exportaciones de datos y la referencia de Crear una exportación.

Centro de privacidad y solicitudes del titular

Las decisiones de cookies no aparecen en el Centro de privacidad. El Centro opera sobre plantillas de consentimiento, y los permisos de cookies no pertenecen a ninguna.

POST /consent_revocations tampoco puede revocarlas, porque exige un consent_template_id. Una solicitud del titular sobre user.device.* no consulta ni revoca los permisos de cookies.

Hoy la única vía de cambio para el titular es el banner o el panel de preferencias. Para tu equipo, el dashboard en modo lectura y las exportaciones.

Revisa Centro de privacidad, Gestión de consentimiento y cómo cambiar preferencias.

Una sola Entity para cookies y consentimiento​

La Entity nace al emitir el token​

Sujetos fusionados​

Qué materializa Soyio​

Entérate desde tu backend​

Cuando la materialización falla​

Exporta las decisiones​

Centro de privacidad y solicitudes del titular​