Gestiona consentimientos

Gestiona consentimientos

El portal de gestión para usuarios finales está disponible solo para el SDK Web. La revocación iniciada por la compañía se realiza vía API backend.

Revocación iniciada por la compañía

Si necesitas revocar consentimientos desde tus sistemas internos por eventos de negocio (por ejemplo, cierre de cuenta o fin de contrato), revisa Revocación de consentimiento (iniciada por la compañía).

Los usuarios tienen el derecho fundamental de gestionar su consentimiento y revocarlo en cualquier momento. Soyio te proporciona las herramientas necesarias para cumplir con este requisito legal de manera transparente y auditable.

Usa el componente Privacy Center del SDK de Soyio para disponer de un portal de gestión de consentimientos donde tus usuarios pueden:

• Ver todos sus consentimientos de forma centralizada con su estado actual (otorgado/no otorgado).
• Ver los consentimientos organizados por alcance (producto/sucursal) cuando habilitas groupConsentsByScope.
• Revisar metadatos clave en el detalle del consentimiento, como alcance y duración (incluyendo duración condicional).
• Revocar y otorgar consentimientos específicos de forma sencilla.

Modos de integración

El Privacy Center puede integrarse en dos modos diferentes según tus necesidades:

Modo público: Utiliza este modo para proporcionar acceso universal a la gestión de consentimientos a cualquier usuario que visita tu sitio web.

• No requiere autenticación previa del usuario.
• Permite que cualquier usuario que visita tu sitio web gestione sus consentimientos.
• Utiliza el local storage para identificar al usuario.

Modo autenticado: Utiliza este modo para proporcionar acceso a la gestión de consentimientos a usuarios autenticados en tu aplicación.

• Requiere que previamente autentiques al usuario.
• Permite que solo los usuarios autenticados gestionen sus consentimientos.
• Utiliza tokens de sesión como medida de seguridad.

Integración en modo público

Usa el componente Privacy Center del SDK Web y configúralo en modo público usando el company_id de tu empresa. Especifica la opción ConsentManagement en el array enabledFeatures para habilitar específicamente el portal de gestión de consentimientos.

El componente automáticamente identifica al usuario y despliega los consentimientos con el estado actual de los consentimientos otorgados o revocados por el usuario.

SDK Web

page.js

import { PrivacyCenter } from "@soyio/soyio-widget";

const privacyCenterOptions = {
  companyId: "<company_id>",
  enabledFeatures: ['ConsentManagement'],
  onEvent: (event) => console.log('Event:', event),
  onReady: () => console.log('Privacy Center is ready'), // Optional
  appearance: {},                                        // Optional
  isSandbox: false,                                      // Optional
};

page.html

<div id="privacy-center-container"></div>

Integración en modo autenticado

Usa el componente Privacy Center del SDK de Soyio y configúralo en modo autenticado para permitir que solo usuarios autenticados en tu aplicación puedan gestionar sus consentimientos.

Flujo de inicialización

El flujo de inicialización para el modo autenticado es el siguiente:

1. El usuario autenticado ingresa a la sección de revocación de consentimientos y el frontend solicita el token de sesión al backend.
2. El backend solicita el token de sesión a la API de Soyio y lo devuelve al frontend.
3. El frontend inicializa el Privacy Center con el token de sesión.
4. El Privacy Center se despliega mostrando los consentimientos del usuario.

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Obtén el token de sesión

Usa el endpoint /api/v1/privacy_center/session_token para obtener el token de sesión. Este endpoint requiere el entity_id o el identity_id de la entidad para la cual se generará el token.

POST /api/v1/privacy_center/session_token

{
    "entity_id": "<entity_id>"
}

Consulta Obtener un token de sesión para el centro de privacidad para revisar parámetros, respuestas y errores del endpoint.

Configura el Privacy Center

Configura el componente Privacy Center del SDK de Soyio usando el session_token obtenido y especifica la opción ConsentManagement en el array enabledFeatures para habilitar específicamente el portal de gestión de consentimientos.

SDK Web

page.js

import { PrivacyCenter } from "@soyio/soyio-widget";

const privacyCenterOptions = {
  sessionToken: "<session_token>",
  enabledFeatures: ['ConsentManagement'], // Habilita el portal de gestión de consentimientos
  onEvent: (event) => console.log('Event:', event)
};

const privacyCenter = new PrivacyCenter(privacyCenterOptions);
privacyCenter.mount("#privacy-center-container");

page.html

<div id="privacy-center-container"></div>

Configuración avanzada

El Privacy Center permite configurar aspectos avanzados del comportamiento de la gestión de consentimientos mediante parámetros adicionales en la inicialización:

Controles de consentimiento

Puedes elegir el tipo de control visual que se utilizará para otorgar o revocar consentimientos.

consentControl: 'switch' (por defecto) | 'checkbox'

const privacyCenterOptions = {
  // ...
  consentControl: 'checkbox' // Usa casillas de verificación en lugar de switches
};

Modo de operación (modo batch)

Por defecto, los cambios de consentimiento se aplican inmediatamente. Puedes configurar el modo batch para permitir al usuario realizar múltiples cambios y guardarlos en una sola acción.

• consentMode: 'immediate' (por defecto) | 'batch'
• showBatchConsentConfirmation: boolean. Muestra un diálogo de confirmación antes de guardar en modo batch.

En modo batch, aparecerá un botón "Guardar" para confirmar los cambios acumulados.

const privacyCenterOptions = {
  // ...
  consentMode: 'batch',
  showBatchConsentConfirmation: true // Muestra un diálogo de confirmación antes de guardar
};

Periodo de retención

Puedes definir un periodo durante el cual un consentimiento otorgado no puede ser revocado inmediatamente. Esto es útil para garantizar la estabilidad operativa de ciertos servicios.

consentRetentionPeriod: string (e.g. '30 days', '1 week'). Unidades soportadas: day, week, month, year.

Cuando se configura, si el usuario intenta revocar un consentimiento dentro del periodo de retención, el control aparecerá deshabilitado.

const privacyCenterOptions = {
  // ...
  consentRetentionPeriod: '30 days'
};

Selección granular de alcance

Si tus plantillas tienen múltiples alcances (scopes), puedes habilitar la selección granular para que el usuario decida por alcance dentro de un mismo consentimiento.

allowGranularScopeSelection: boolean (por defecto false).

const privacyCenterOptions = {
  // ...
  allowGranularScopeSelection: true
};

Con esta configuración, el usuario verá casillas de verificación por alcance en el detalle del consentimiento y el control principal podrá quedar en estado parcial cuando solo algunos alcances estén activos.

Visualización agrupada por alcance

Si necesitas ordenar muchos consentimientos por producto o sucursal, habilita la visualización agrupada por alcance.

groupConsentsByScope: boolean (por defecto false).

Con esta configuración:

• Los consentimientos con alcance se muestran en acordeones por alcance.
• Los consentimientos sin alcance se muestran en una sección general.

const privacyCenterOptions = {
  // ...
  groupConsentsByScope: true
};

Puedes combinar groupConsentsByScope con allowGranularScopeSelection para agrupar consentimientos y mantener la selección granular por alcance dentro de cada template.

Persistencia de consentimientos superpuestos

En el modelo de datos de Soyio, los consentimientos se gestionan a nivel de permisos individuales (combinación de Uso de Dato + Categoría de Dato). Es común que diferentes Plantillas de Consentimiento compartan ciertos permisos (superposición).

El sistema maneja esta superposición utilizando una lógica de unión:

1. Otorgamiento (Grant): Al otorgar una plantilla, se agregan todos sus permisos al acuerdo del usuario. Si un permiso ya existía (por otra plantilla activa), se mantiene.
2. Revocación (Revoke): Al revocar una plantilla, se eliminan los permisos asociados a ella, EXCEPTO aquellos que son requeridos por otra plantilla que el usuario mantenga activa.

Esto asegura que siempre se respeten todas las autorizaciones vigentes del usuario, sin revocar permisos accidentalmente que son necesarios para otros fines aceptados.

Efecto de la modificación de consentimientos

Mensajes en la interfaz del usuario

Cuando el usuario otorga o revoca un consentimiento en el portal de gestión de consentimientos, se muestra un mensaje informativo sobre el tiempo que podría tomar en reflejarse el cambio en los sistemas de tu empresa. Por defecto se indica que puede tardar hasta 7 días.

Actualización de los consentimientos

Una vez que el usuario otorgue o revoque un consentimiento en el portal de gestión de consentimientos, se modificará automáticamente en la base de datos de Soyio, tanto en el agreement como en la evidencia asociada. Recomendamos consultar el estado de consentimiento antes de realizar cualquier tratamiento de datos.

Revisa la guía de consulta de consentimiento para obtener más información sobre cómo consultar el estado de los consentimientos.

Eventos en el backend

Soyio envía webhooks para notificar cuando el usuario otorga o revoca un consentimiento en el portal de gestión de consentimientos. En este caso en particular se envían los eventos:

• agreement.updated: Se ha actualizado un agreement.
• consent_action.created: Se ha creado una nueva acción de consentimiento que puede ser revoke o grant.

Escucha estos eventos en tu backend para mantener tu sistema actualizado en tiempo real y reaccionar inmediatamente a las decisiones de tus usuarios.

Revisa la guía de webhooks para obtener más información sobre cómo configurar y suscribirte a los webhooks.

Revocación de consentimiento (iniciada por la compañía)

Además de la revocación iniciada por el usuario, puedes revocar consentimientos de forma programática desde tus sistemas internos.

Este flujo es útil para casos como:

• término de contrato o cierre de cuenta,
• cambios de estado de cliente que invalidan permisos previos,
• cumplimiento de políticas internas de negocio.

Endpoint:

POST /api/v1/consent_revocations

Parámetros clave:

• Identificación del sujeto (identity_id, entity_id o user_reference).
• consent_template_id.
• reason_code.
• origin_event (system, event_id, occurred_at).
• selected_scopes (opcional): para revocar solo un subconjunto de alcances en templates multi-alcance.

Para revisar validaciones y respuestas del endpoint, consulta Crear una revocación de consentimiento iniciada por la empresa.

Reglas importantes

Este endpoint aplica guardrails de revocación. En particular:

• el template debe tener duration_type="conditional",
• el template debe tener revocable_data_uses configurado,
• selected_scopes (si se envía) debe ser subconjunto de los scopes del template.

Ejemplo:

curl -X POST \
  https://api.soyio.id/api/v1/consent_revocations \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_reference": "user-external-id-987",
    "consent_template_id": "constpl_1B2M2Y8AsgTpgAmY7PhCfg",
    "reason_code": "account_closure",
    "origin_event": {
      "system": "crm_system",
      "event_id": "evt_xyz123",
      "occurred_at": "2026-02-11T15:10:00Z"
    }
  }'

Si necesitas consultar una revocación ya creada, revisa Obtener una revocación de consentimiento iniciada por la empresa y CompanyConsentRevocation.