Saltar al contenido principal

Obtención de consentimiento (Consent)

Integra un componente de consentimiento directamente en tu flujos para capturar uno más consentimientos explícitos de tus usuarios.

Este módulo te permite cumplir con las regulaciones de protección de datos personales al obtener y registrar el consentimiento de tus usuarios de manera transparente, granular y sin interrumpir su experiencia de compra.

Información

Por ahora, este servicio está disponible sólo para el SDK Web.

Cada vez que el usuario marque el checkbox de consentimiento, se creará un registro de consentimiento mediante un token de acción. Este token se puede usar para crear un registro de consentimiento en el backend y generar evidencia del consentimiento otorgado.

A grandes rasgos, el módulo Consent Box te permite:

  • Obtener consentimiento informado: Registra la autorización explícita para el uso de datos. El usuario podrá revisar qué usos se harán de sus datos.
  • Obtener consentimiento múltiple o granular: Permite obtener el consentimiento de una o más categorías de uso de datos.
  • Integración fluida: Embebe el componente directamente en tu interfaz y personalizalo con el look and feel de tu aplicación
  • Generar confianza: Informamos al usuario sobre el uso de sus datos de manera transparente y clara, utilizando simbología sencilla y dando la opción de más información directamente en el componente.
  • Evidencia vinculante: Genera evidencia del consentimiento otorgado mediante un agreement y evidencia.
tip

Puedes averiguar más acerca de nuestra simbología y taxonomía en la guía de Taxonomía y gestión de datos.

El proceso de consentimiento​

El proceso de consentimiento embebido se compone de los siguientes pasos:

  1. Se muestra el componente de consentimiento al usuario en un formulario o sección de tu interfaz
  2. El usuario revisa y acepta los términos mediante un checkbox opt-in.
  3. Se genera un token de acción cada vez que el usuario haga click un checkbox de consentimiento.
  4. Al momento de persistir los datos del usuario, se envían los token de acción para crear un registro de consentimientos (ConsentAction) con evidencia del proceso.
  5. Con base en estas acciones de consentimiento, el sistema automáticamente crea o actualiza los Agreements para el usuario. El Agreement es la fuente de verdad que determina qué permisos tiene un usuario para el uso de sus datos.
  6. Para verificar si puedes utilizar un dato para una finalidad específica, siempre debes consultar el Agreement actualizado.
Información

Los Agreements pueden cambiar a lo largo del tiempo debido a nuevas acciones de consentimiento, modificaciones o revocaciones. Por eso, siempre es recomendable consultar el Agreement actual a través de la API de Soyio.

Modalidades de consentimiento​

Este módulo soporta dos modalidades de acuerdo a como se necesite obtener el consentimiento de los usuarios

Información

La configuración de la modalidad de consentimiento se determina de acuerdo a la estructura de los data_uses dentro de los data_requirements del consent_template creado. Revisa la sección de plantilla de consentimiento para más detalles.

Consentimiento Unificado​

Permite capturar el consentimiento de múltiples categorías de uso de datos en un sólo click. Útil para tratamiento de datos y formularios simples y de una sola página, donde el usuario puede revisar y aceptar todos los usos de datos en un solo paso.

Consent Embed example

Consentimiento Granular​

Permite obtener el consentimiento de una categoría de uso de datos específica. Útil para formularios con lógica más compleja, donde por ejemplo, el tratamiento de datos ocurre en el transcurso de completar el formulario (carrito abandonado, etc). Esto también permite mayor flexibilidad en la lógica de captura de datos, ya que puedes capturar el consentimiento de una categoría de uso de datos específica en un momento específico del flujo.

Consent Embed example

Ejemplo​

A continuación, te mostramos un ejemplo de integración del componente de consentimiento implementado en un formulario.



Puedes utilizar este ejemplo como base para integrar el componente en tu aplicación. Más adelante encontrarás una guía detallada para implementarlo desde cero.

Integración​

El flujo que integrarás es el siguiente:

Pre requisitos​

  1. Tener el SDK instalado en tu sitio o aplicación.
  2. Tener una plantilla de consentimiento creada.
  3. (Opcional) Crear uno o más documentos de privacidad para asociar a la plantilla de consentimiento.

Paso a paso​

1. Crear una plantilla de consentimiento​

Para comenzar, deberás crear una plantilla de consentimiento que defina qué datos y permisos necesitas solicitar a tus usuarios. También podrás asociar uno o más documentos de privacidad a la plantilla.

Importante

Es importante que la plantilla de consentimiento describa de manera correcta los usos que se harán de los datos y que tenga al menos una finalidad y un periodo de retención. Revisa nuestra sección de uso de datos para más detalles.

tip

Considera agregar un product_id al crear la plantilla para poder asociar el consentimiento de los datos a un producto en particular. Esto facilitará la gestión y organización de los consentimientos por producto.

De acuerdo a la estructura de los data_uses dentro de los data_requirements del consent_template creado, se creará o un consentimiento unificado o granular.

A continuación, te mostramos un ejemplo de creación de una plantilla de consentimiento para cada modalidad:

Este template creará un consentimiento unificado ya que los data_uses provienen de diferentes categorías raíz.

POST /api/v1/consent_templates
{
  "name": "Template de consentimiento unificado",
  "availability_period_in_months": 12,
  "text": "De acuerdo a los {{ terms_and_conditions }} y {{ privacy_policy }}, autorizo el uso de mis datos personales.",
  "data_requirements": [
    {
      "key": "email",
      "data_uses": [
        "essential",
        "marketing",
        "third_party_sharing"
      ]
    },
    {
      "key": "phone_number",
      "data_uses": [
        "essential",
        "marketing"
      ]
    }
  ]
}

2. Inicializa el componente en tu frontend​

Inicializa el componente de consentimiento en tu interfaz mediante el SDK de Soyio, utilizando el id del consent_template creado previamente. Estos empiezan con el prefijo constpl_.

tip

El parámetro context en las opciones de configuración te permite asociar el consentimiento a un contexto específico, lo que facilita la organización y seguimiento de los consentimientos según diferentes casos de uso.

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

// Configuración del componente
const consentOptions = {
    templateId: "<consent_template_id>",
    onEvent: (data) => console.log(data),
    isSandbox: false,                                  // Optional
    appearance: {},                                    // Optional
    context: "<context_of_the_current_consent>",       // Optional
    actionToken: "<previously_created_action_token>",  // Optional
    entityId: "<entity_id_of_existing_consent_action>" // Optional
};

// Montar el componente
document.addEventListener("DOMContentLoaded", () => {
    const consentBox = new ConsentBox(consentOptions);
    consentBox.mount("#consent-box-container");
});
<!-- HTML -->
<div id="consent-box-container"></div>
info

Para más información sobre la configuración del componente, consulta la documentación de la SDK web.

tip

Este módulo está diseñado para integrarse de manera nativa en tu interfaz y podrás personalizarlo con el look and feel de tu aplicación. Revisa la sección de personalización para más detalles.

3. Escucha los eventos del componente o consulta el estado de consentimiento​

El parámetro de actionToken es necesario para crear el registro de consentimiento luego en el siguiente paso. Para ello, tienes dos opciones:

El componente emitirá eventos cuando el usuario interactúe con él. El evento principal es CONSENT_CHECKBOX_CHANGE que incluye:

{
    eventName: 'CONSENT_CHECKBOX_CHANGE',
    isSelected: boolean,
    actionToken: string
}

De esta manera, puedes obtener el actionToken en el instante en que el usuario haga click en el checkbox.

3.2 Consultar el estado de consentimiento directamente​

También puedes consultar por el estado del consentimiento (útil para submits de formularios) mediante la función getStatus de la instancia del ConsentBox. Este método retorna un objeto con el siguiente formato:

{
    isSelected: boolean,
    actionToken: string | undefined
}

Por ejemplo:

const status = consentBox.getStatus();

4. Crea el registro de consentimiento​

tip

Si tu interfaz tiene múltiples módulos de consentimiento, considera usar el registro agrupado para una gestión más eficiente de los consentimientos.

Una vez que tengas el actionToken, puedes crear el registro de consentimiento mediante el endpoint de creación de acción de consentimiento.

Opcionalmente, puedes agregar el userReference para asociar el consentimiento con un usuario específico de tu sistema.

POST /api/v1/consent_actions
{
    "action_token": "<action_token>",
    "user_reference": "<identificador_usuario>" // Opcional
}

4.1 Registro agrupado​

Opcionalmente, puedes crear un registro de consentimiento agrupado (por ejemplo, cuando se termina un formulario o para capturar varios tipos de consentimientos en un solo submit) mediante el endpoint de commit de consentimientos. Esto te permitirá agrupar varios action tokens en un solo registro de consentimiento.

POST /api/v1/consent_commits
{
    "consent_actions": [
      { "action_token": "<action_token_1>" },
      { "action_token": "<action_token_2>" }
    ],
    "user_reference": "<identificador_usuario>" // Opcional
}

Una vez se haya creado el registro de consentimiento, se retornará la acción (o lista de acciones) creada(s). En cada una de ellas, habrá un entity_id, junto con el user_reference (en el caso de que se haya proporcionado), que representa el identificador único del usuario que otorgó el consentimiento.

5. Consulta y gestión de consentimientos a través de Agreements​

Una vez creados los consentimientos a través de ConsentActions, el sistema de Soyio automáticamente crea o actualiza los Agreements para la entidad (usuario). Los Agreements son la fuente de verdad que determina si para un usuario específico puede hacerse uso de un dato para una finalidad específica.

5.1 El flujo de consentimiento y Agreements​

  1. Creación de ConsentActions: Cuando se crea un registro de consentimiento mediante el endpoint de acciones de consentimiento, se genera un ConsentAction que hace referencia al template utilizado.

  2. Actualización de Agreements: En base a las acciones de consentimiento, el sistema de Soyio crea o actualiza los permisos del usuario (Entity) en su Agreement, donde se refleja el estado actual de los consentimientos otorgados.

  3. Consulta de permisos: Para verificar si puedes utilizar un dato específico para una finalidad concreta, siempre debes consultar el Agreement y no basarte en la información del template o de las acciones de consentimiento individuales. Ofrecemos dos opciones para consultarlo a través de nuestra API detalladas en las siguientes secciones.

Importante

Los Agreements pueden cambiar a lo largo del tiempo debido a nuevas acciones de consentimiento, modificaciones o revocaciones. Por esto, la información del template no refleja si existen cambios en el consentimiento que inicialmente se otorgó.

5.2 Consulta del estado de cumplimiento de un template​

Para saber si un usuario ha otorgado consentimiento a un template en particular, y estos siguen siendo válidos, puedes consultar el endpoint del estado de cumplimiento (ComplianceStatus) para un template / entidad específica

El ComplianceStatus es un objeto que refleja si el usuario cumple (compliant) con todos los requerimientos (data_requirements) del template que utilizaste.

Puede también cumplir parcialmente (partially_compliant) o no cumplir (non_compliant).

GET /api/v1/entities/<entity_id>/agreement/compliance_statuses
{
    "compliance_statuses": [
        {
            "consent_template_id": "<consent_template_id>",
            "entity_id": "<entity_id>",
            "last_consent_action_id": "<last_consent_action_id>",
            "status": "compliant"
        }
    ]
}

Puedes filtrar por consent_template_id para obtener el estado de cumplimiento de un template en particular.

5.3 Consulta de Agreements​

Si bien ofrecemos el ComplianceStatus, también puedes consultar el Agreement directamente a través del endpoint de listado de Agreements filtrando por el ID de la entidad o el user_reference:

GET /api/v1/agreements?entity_id=<entity_id>

La respuesta te proporcionará la información actual sobre qué datos puede utilizar y para qué finalidades, a través del atributo data del Agreement.

tip

Puedes guardar la última versión del Agreement (que enviamos mediante webhooks, específicamente los que tienen el nombre agreement.*) como un caché local para consultas rápidas o en caso de respaldo. Sin embargo, siempre recomendamos verificar el estado actual del Agreement a través de nuestra API para asegurar que estás trabajando con la información más actualizada.

Personalización (Opcional)​

El componente puede ser personalizado para poder adaptarse a tu interfaz mediante variables de CSS declaradas en el objeto appearance del SDK. Por ejemplo:

const consentOptions = {
    templateId: "<consent_template_id>",
    appearance: {
      variables: {
          fontFamily: 'system-ui, sans-serif',
          colorPrimary: '#f54c27',
          colorBackground: '#ffffff',
      },
      rules : {
          '.Checkbox': {
            accentColor: 'var(--colorPrimary)',
          }
      }
};
Pro Tip

Para obtener más información sobre las variables y reglas de personalización, consulta la documentación oficial del SDK web de Soyio.

Importante

Asegúrate de mantener los elementos de accesibilidad como el contraste adecuado y el tamaño de fuente legible al personalizar el componente.