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 { PrivacyCenterBox } 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], 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://app.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 { PrivacyCenterBox } 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 PrivacyCenterBox(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.

appearance.config.consentControl: 'switch' (por defecto) | 'checkbox'

const privacyCenterOptions = {
  // ...
  appearance: {
    config: { 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.

Aviso de consentimientos requeridos

En la vista de gestión, cada consentimiento requerido (no revocable) muestra un aviso que indica que es obligatorio y ofrece un enlace para ejercer los derechos. Puedes personalizar ese texto de forma genérica, para todos los consentimientos requeridos, u ocultarlo.

appearance.config.showRequiredConsentNotice: boolean (por defecto true). Si lo defines como false, el aviso no se muestra en ningún consentimiento requerido.
content.consentManagement.requiredConsentNotice.text: string. Reemplaza el texto por defecto del aviso. No se traduce: se muestra tal cual lo envíes. Puedes envolver un fragmento con {link} y {/link} para mostrarlo como enlace; puedes repetir el marcador y todos apuntan a la misma URL. Si envías un texto vacío o solo con espacios, el aviso no se muestra.
content.consentManagement.requiredConsentNotice.linkUrl: string opcional. Destino del enlace. Acepta URLs http, https y mailto. Si no lo envías o no es válido, el enlace usa el mismo destino que el aviso por defecto (externalRightsExerciseUrl, la URL pública del centro de privacidad, el correo de contacto de la empresa o el formulario interno de solicitudes de derechos si está habilitado).

Configuración	Resultado
Nada configurado	Se muestra el texto por defecto.
`appearance.config.showRequiredConsentNotice: false`	No se muestra el aviso.
`text` vacío o solo con espacios	No se muestra el aviso.
`text` con contenido	Se muestra el texto tal cual, sin traducir.

const privacyCenterOptions = {
  // ...
  appearance: {
    config: {
      showRequiredConsentNotice: true // Pon false para ocultar el aviso
    }
  },
  content: {
    consentManagement: {
      requiredConsentNotice: {
        text: 'Este consentimiento es necesario para el servicio. Revisa {link}nuestros términos{/link}.',
        linkUrl: 'https://example.com/terminos'
      }
    }
  }
};

También puedes ocultar el aviso con el flag o con un texto vacío:

const privacyCenterOptions = {
  // ...
  appearance: {
    config: { showRequiredConsentNotice: false }
  }
};

El texto personalizado no se interpreta como HTML; solo se convierte en enlaces lo que envuelvas con {link} y {/link}. Las etiquetas sin cerrar o mal escritas se muestran literalmente.

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.

consentManagement.scopeGroups[].defaultOpen: boolean (por defecto false). Requiere groupConsentsByScope: true. Si lo defines como true, ese grupo se muestra desplegado la primera vez que se renderiza la vista. Puedes marcarlo en varios grupos y todos partirán abiertos. La elección del usuario al abrir o cerrar un grupo se mantiene, aunque luego llegue una actualización de configuración.

const privacyCenterOptions = {
  // ...
  groupConsentsByScope: true,
  consentManagement: {
    allowMultipleOpenScopeGroups: false,
    scopeGroups: [
      {
        title: 'Productos financieros',
        defaultOpen: true,
        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, y el catálogo de eventos para ver el contrato de cada uno.

Actualización de versiones de templates

Cuando actualizas un template de consentimiento, Soyio crea una nueva versión. El portal de gestión de consentimientos distingue automáticamente dos escenarios para los usuarios que aceptaron una versión anterior:

La nueva versión requiere más permisos

El usuario sigue viendo el contenido de la versión que aceptó, marcada como otorgada. Junto a ella aparece un aviso con los datos y usos adicionales que solicita la nueva versión y un botón para aceptarla. Al usarlo, se otorga la última versión del template mediante el flujo normal de consentimiento.

Aviso de nueva versión de consentimiento con los datos adicionales y el botón para aceptarla

Esto también aplica a los consentimientos requeridos: se muestran como otorgados con el mismo aviso y botón.

La nueva versión no requiere permisos adicionales

Si la autorización vigente del usuario sigue cubriendo la nueva versión (por ejemplo, cuando solo cambia el nombre de un producto), el consentimiento se mantiene como otorgado y no se muestra ningún aviso: el usuario no necesita hacer nada.

Consulta por API qué versión aceptó cada usuario y los cambios pendientes usando expand[]=accepted_version. Revisa la guía de consulta de consentimiento.

Consentimientos con una lista de exclusión

Si el usuario está en una lista de exclusión que cubre lo que pide un consentimiento, el Privacy Center muestra lo que realmente se aplica, no solo lo que el usuario otorgó. Requiere que tu cuenta tenga habilitado el módulo de listas de exclusión.

Si la restricción cubre todo el consentimiento, aparece como no otorgado.
Si cubre solo una parte, el control queda en estado parcial (solo con consentControl: 'checkbox').
Junto al consentimiento aparece un aviso con los datos y usos restringidos y el nombre de la lista.
Si el usuario vuelve a otorgar el consentimiento, se registra un consentimiento nuevo que reemplaza a la restricción.

Si tu empresa hace prevalecer siempre las restricciones (restrictions_always_prevail, en la configuración de listas de exclusión), un consentimiento nuevo no las reemplaza:

Si la restricción cubre todo el consentimiento, el control queda deshabilitado.
Si cubre solo una parte, el usuario puede revocar la parte que sigue vigente.

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://app.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, y todos los eventos que emite Soyio en el catálogo de eventos.

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​

Aviso 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​

Actualización de versiones de templates​

La nueva versión requiere más permisos​

La nueva versión no requiere permisos adicionales​

Consentimientos con una lista de exclusión​

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

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

Eventos del frontend para tracking en tiempo real​

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

Aviso 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

Actualización de versiones de templates

La nueva versión requiere más permisos

La nueva versión no requiere permisos adicionales

Consentimientos con una lista de exclusión

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

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

Eventos del frontend para tracking en tiempo real