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 ejemplos de esta página están alineados con @soyio/soyio-widget v3+. Si personalizas la apariencia del portal, usa theme + mode como modelo principal. theme: 'night' sigue siendo aceptado por compatibilidad, pero se considera deprecado.

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.
Ver grupos personalizados de acordeones por conjunto de alcances cuando defines consentManagement.scopeGroups.
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:

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

Obtén el token de sesión

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

Si también habilitarás el flujo de ejercicio de derechos en modo autenticado, envía opcionalmente config[cl_carnet_rut] para prellenar y bloquear el RUT del usuario durante esa sesión.

GET /api/v1/privacy_center/session_token
curl --request GET \
  --url 'https://api.soyio.id/api/v1/privacy_center/session_token?entity_id=<entity_id>&config[cl_carnet_rut]=<user_rut>' \
  --header 'Authorization: Bearer <your_process_token>'

Si usas config[cl_carnet_rut], cualquier DSR creado con ese token deberá enviar contact_information.nin con el mismo valor o la API rechazará la solicitud con 422.

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

config[cl_carnet_rut] es un parámetro opcional adicional para el flujo de DSR autenticado y puede no aparecer de inmediato en la referencia autogenerada si está desactualizada.

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:

Para una guía más completa de personalización visual y de comportamiento, revisa Apariencia y comportamiento del Privacy Center y la guía general de apariencia.

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'
};

Revocación de consentimientos requeridos

Por defecto, el Privacy Center permite que los usuarios revoquen consentimientos requeridos desde la UI de gestión.

Si necesitas impedir ese comportamiento para tu empresa, puedes deshabilitarlo con la configuración backend privacy_center.allow_required_consent_revocation.

privacy_center.allow_required_consent_revocation: boolean (por defecto true).

Cuando esta configuración está en false:

los consentimientos requeridos dejan de ser revocables para el usuario final en el Privacy Center
el comportamiento aplica tanto a la UI como a las validaciones backend

Puedes actualizar esta configuración usando tus endpoints de configuración de empresa en Soyio.

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.

Grupos personalizados de acordeón

Si necesitas agrupar múltiples alcances en categorías de negocio (por ejemplo, "Productos financieros" o "Sucursales principales"), puedes definir grupos personalizados.

consentManagement.scopeGroups: array opcional. Requiere groupConsentsByScope: true.

Cada grupo debe incluir title y scopes.
Cada alcance en scopes debe tener { scopeType: 'product' | 'branch', scopeId: string }.
Los alcances no incluidos en scopeGroups se siguen mostrando con el agrupado por alcance por defecto.

consentManagement.allowMultipleOpenScopeGroups: boolean (por defecto true). Requiere groupConsentsByScope: true. Si lo defines como false, abrir un acordeón cierra el resto.

const privacyCenterOptions = {
  // ...
  groupConsentsByScope: true,
  consentManagement: {
    allowMultipleOpenScopeGroups: false,
    scopeGroups: [
      {
        title: 'Productos financieros',
        scopes: [
          { scopeType: 'product', scopeId: 'prod_checking_account' },
          { scopeType: 'product', scopeId: 'prod_credit_card' }
        ]
      },
      {
        title: 'Sucursales principales',
        scopes: [
          { scopeType: 'branch', scopeId: 'branch_centro' },
          { scopeType: 'branch', scopeId: 'branch_providencia' }
        ]
      }
    ]
  }
};

Encabezado interno de gestión de consentimientos

Puedes ocultar o personalizar el encabezado de la pantalla de gestión de consentimientos sin afectar el encabezado principal del Privacy Center.

appearance.config.showConsentManagementHeader: boolean (por defecto true). Muestra u oculta el encabezado de la pantalla de gestión de consentimientos.
content.consentManagement.header.title: string.
content.consentManagement.header.description: string.

const privacyCenterOptions = {
  // ...
  appearance: {
    config: {
      showConsentManagementHeader: true
    }
  },
  content: {
    consentManagement: {
      header: {
        title: 'Gestiona tus permisos',
        description: 'Configura qué autorizaciones quieres mantener activas.'
      }
    }
  }
};

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:

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.
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.

Modos de integración​

Integración en modo público​

Integración en modo autenticado​

Flujo de inicialización​

Obtén el token de sesión​

Configura el Privacy Center​

Configuración avanzada​

Controles de consentimiento​

Modo de operación (modo batch)​

Periodo de retención​

Revocación de consentimientos requeridos​

Selección granular de alcance​

Visualización agrupada por alcance​

Grupos personalizados de acordeón​

Encabezado interno de gestión de consentimientos​

Persistencia de consentimientos superpuestos​

Efecto de la modificación de consentimientos​

Mensajes en la interfaz del usuario​

Actualización de los consentimientos​

Eventos en el backend​

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

Modos de integración

Integración en modo público

Integración en modo autenticado

Flujo de inicialización

Obtén el token de sesión

Configura el Privacy Center

Configuración avanzada

Controles de consentimiento

Modo de operación (modo batch)

Periodo de retención

Revocación de consentimientos requeridos

Selección granular de alcance

Visualización agrupada por alcance

Grupos personalizados de acordeón

Encabezado interno de gestión de consentimientos

Persistencia de consentimientos superpuestos

Efecto de la modificación de consentimientos

Mensajes en la interfaz del usuario

Actualización de los consentimientos

Eventos en el backend

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