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

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 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], config[names], config[last_names], config[email] y config[phone] para prellenar y bloquear los campos correspondientes 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>&config[names]=<user_names>&config[last_names]=<user_last_names>&config[email]=<user_email>&config[phone]=<user_phone>' \
  --header 'Authorization: Bearer <your_process_token>'

Si usas config[cl_carnet_rut], cualquier DSR creado con ese token debe enviar contact_information.nin con el mismo valor o la API responderá 422. Los campos config[names], config[last_names], config[email] y config[phone] solo prellenan la UI; no se validan al enviar la solicitud.

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.

Esta sección cubre opciones específicas de consentimiento. Para textos comunes del contenedor, revisa Contenido y configuración común del Privacy Center. Para estilos visuales, usa 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:

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_data_uses (opcional): para revocar solo un subconjunto de data uses del template.
• 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 puede tener duration_type="fixed" o duration_type="conditional",
• si envías selected_data_uses, deben existir en el template,
• si el template tiene revocable_data_uses, selected_data_uses debe respetar ese guardrail,
• si no envías selected_data_uses y el template no tiene revocable_data_uses, se intentan revocar todos los data uses del template,
• 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",
    "selected_data_uses": ["third_party_sharing.intra_company"],
    "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.

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

Usa una corrección cuando tus sistemas internos detecten que un consentimiento quedó con un alcance más amplio del que correspondía, por ejemplo por un error de integración o por una asignación incorrecta de producto o sucursal.

Antes de aplicar la corrección, ejecuta el modo preview o dry run:

POST /api/v1/consent_corrections/preview

El preview no crea una corrección, no genera una nueva versión del agreement y no altera la evidencia. Solo devuelve el resultado esperado: permisos actuales, permisos que quedarían retenidos, estado esperado (applied, no_changes o empty_result) y advertencias si la corrección sería rechazada.

Cuando el preview sea correcto, aplica la corrección con:

POST /api/v1/consent_corrections

Si necesitas revertir una corrección aplicada, usa el rollback:

POST /api/v1/consent_corrections/{id}/rollback

El rollback no modifica ni elimina el historial: crea una nueva versión del agreement restaurando los permisos de la versión anterior a la corrección y mantiene la trazabilidad de evidencia.

Eventos del frontend para tracking en tiempo real

El Privacy Center expone eventos vía onEvent cuando un usuario otorga o revoca un consentimiento desde la UI:

• CONSENT_UPDATED: el cambio de consentimiento se completó con éxito en el modo immediate (incluye action: 'grant' | 'revoke').
• CONSENT_UPDATE_FAILED: el cambio falló en el modo immediate.
• CONSENT_BATCH_UPDATED: el usuario guardó con éxito un conjunto de cambios en el modo batch. Trae el array completo de updates en un solo evento, en lugar de emitir uno por cada consentimiento.
• CONSENT_BATCH_UPDATE_FAILED: el guardado del conjunto falló en el modo batch.

Úsalos para tracking de analítica o para sincronizar UI fuera del Privacy Center sin esperar a los webhooks de backend.

Revisa la lista completa de eventos y un ejemplo de uso en Eventos del Privacy Center.