Integración sin SDK

⭐Disponible como add-on

Esta funcionalidad está disponible como add-on en ciertos planes. Consulta por los planes completando el siguiente formulario.

Sigue esta guía para registrar consentimientos sin usar el SDK de Soyio. Esta opción te permite usar el motor de consentimiento, evidencia y trazabilidad de Soyio programando tus propias interfaces con nuestras APIs.

Es la opción ideal si:

Ya tienes tu propia interfaz o lógica de consentimiento
Quieres lograr una experiencia full white label programando tus propias interfaces
Necesitas integrar Soyio en sistemas que no soportan componentes embebidos

Ventajas principales

Flexibilidad total en la implementación
Control absoluto sobre la experiencia de usuario
Integración ligera, sin dependencias adicionales

Trazabilidad y Responsabilidad

Cuando integras Soyio, es importante entender las diferencias de trazabilidad entre el SDK y la integración directa vía API:

Aspecto	Con SDK de Soyio	Con API directa
Trazabilidad	✅ End-to-end garantizada	⚠️ Responsabilidad del comercio
Interacción con usuario	Widget en iframe aislado	Tu propia interfaz
Tokenización	✅ Automática	✅ Via API (action token)
Contexto de la acción	✅ Capturado automáticamente	⚠️ Debes proporcionarlo
Evidencia	✅ Completa y verificable	⚠️ Depende de tu implementación
Respaldo de datos para trazabilidad de la acción del usuario	✅ Gestionado por Soyio	⚠️ Tu responsabilidad

Detalles de cada enfoque

Con SDK de Soyio

Trazabilidad end-to-end garantizada: El SDK interactúa directamente con el usuario final a través de un widget en un entorno aislado y seguro (iframe)
Tokenización automática: El SDK tokeniza automáticamente la acción del usuario y la entrega al frame padre para que tu backend la persista
Evidencia completa: Soyio garantiza la trazabilidad completa desde la interacción del usuario hasta el registro final

Con integración directa vía API

Responsabilidad del comercio: Al integrar directamente vía API, tú asumes la responsabilidad de la acción del usuario
Contexto obligatorio: Debes incluir toda la información contextual necesaria que permita rastrear la acción hasta tu sistema
Respaldo de evidencia: Es tu responsabilidad mantener el respaldo de la evidencia que respalde la acción del usuario

Después de la acción

Independientemente del enfoque que elijas (SDK o API directa), una vez creado el action token, Soyio se encarga de toda la trazabilidad y auditabilidad desde ese momento en adelante. Esto incluye:

Generación de evidencia verificable
Almacenamiento seguro e inmutable de la evidencia
Capacidad de auditoría completa

Responsabilidad legal

Al usar la API directamente, eres completamente responsable de:

La veracidad de la información proporcionada
El cumplimiento de las normativas de privacidad aplicables
La capacidad de demostrar que el consentimiento fue otorgado de manera válida
El mantenimiento de la evidencia de respaldo

Pre-requisitos

Antes de comenzar, asegúrate de tener:

Cuenta Empresa en Soyio con credenciales de API
Plan que incluya esta funcionalidad contratado
Una plantilla de consentimiento creada

Paso a paso

Para este enfoque, no necesitas el SDK instalado en tu frontend. Crea tokens de acción directamente desde tu backend usando la API de Soyio.

1. Crea o selecciona una plantilla de consentimiento

Usa una plantilla de consentimiento ya creada o crea una nueva plantilla de consentimiento. Revisa la guía de plantillas de consentimiento para más información.

2. Implementa tu propia lógica de consentimiento

Con este enfoque, tienes total libertad para implementar tu propia interfaz y lógica de consentimiento. Sin embargo, te recomendamos encarecidamente obtener la información de la plantilla de consentimiento que creaste para mostrar al usuario las cláusulas, categorías de datos y usos de datos correspondientes. Esto es importante para el cumplimiento normativo y la transparencia de la información.

Obtén información de la plantilla

Antes de mostrar tu interfaz de consentimiento, consulta la plantilla de consentimiento para obtener:

Cláusula del consentimiento (text): El texto explicativo que debes mostrar al usuario
Categorías de datos (data_categories): Los tipos de datos que se recolectarán según la taxonomía de Soyio
Usos de datos (data_uses): Las categorías específicas de uso de datos según la taxonomía de Soyio
Documentos de privacidad asociados: Enlaces a términos y condiciones, políticas de privacidad, etc.

Ventajas de usar la plantilla para generar tu UI

Gestión centralizada: Los cambios en la plantilla de consentimiento se reflejan automáticamente sin modificar código
Consistencia: Mantienes la taxonomía estándar de Soyio para categorías de datos y usos de datos
Cumplimiento: Aseguras que la información mostrada coincide exactamente con lo registrado en la evidencia generada

Manejo de texto formateado en las cláusulas

Las cláusulas de consentimiento (text) pueden contener notación especial de texto formateado que debes procesar en tu interfaz para mostrar correctamente tooltips y referencias a documentos de privacidad. Para entender mejor la estructura completa de una plantilla de consentimiento, revisa la guía de plantillas de consentimiento.

Notación de tooltips

Los tooltips se indican con la siguiente sintaxis:

[[texto visible]](contenido del tooltip)

El texto entre [[ y ]] es lo que se muestra al usuario como trigger del tooltip
El texto entre ( y ) es el contenido que debe aparecer al interactuar con el tooltip

Ejemplo:

Acepto el procesamiento de mis [[datos personales]](información que te identifica como persona)

Deberías renderizar "datos personales" como un elemento interactivo que muestre "información que te identifica como persona" al hacer hover.

Ejemplo de procesamiento:

function processTooltips(text) {
  const tooltipRegex = /\[\[([^\]]+)\]\]\(([^)]+)\)/g;

  return text.replace(tooltipRegex, (match, triggerText, tooltipContent) => {
    return `<span class="tooltip-trigger" data-tooltip="${escapeHtml(tooltipContent)}">${escapeHtml(triggerText)}</span>`;
  });
}

const consentText = "Acepto el procesamiento de mis [[datos personales]](información que te identifica como persona) para los fines descritos.";
const processedHTML = processTooltips(consentText);

Notación de documentos de privacidad

Las referencias a documentos de privacidad se indican con la siguiente sintaxis:

{{ template_key:version }}

template_key es el identificador del documento de privacidad
version es el número de versión del documento

Ejemplo:

Acepto los {{ terms_and_conditions:1 }} y la {{ privacy_policy:2 }}

Para procesar estas referencias:

Extrae el template_key y version del texto
Obtén el documento correspondiente usando el endpoint de obtención de documentos de privacidad con los parámetros de consulta where
Renderiza como un enlace usando el name y url del documento obtenido

Ejemplo de procesamiento:

async function processPrivacyDocuments(text, apiBaseUrl, apiKey) {
  const documentRegex = /\{\{\s*([^:]+):(\d+)\s*\}\}/g;
  const allMatches = [...text.matchAll(documentRegex)];

  // Extract all unique template keys and versions
  const templateKeys = [...new Set(allMatches.map(([, key]) => key.trim()))];
  const versions = [...new Set(allMatches.map(([, , ver]) => Number(ver)))];

  // Build filter for single API request
  const whereFilter = {
    template_key: { in: templateKeys },
    version: { in: versions }
  };

  // Fetch all documents in one request
  const response = await fetch(
    `${apiBaseUrl}/privacy_documents?where=${encodeURIComponent(JSON.stringify(whereFilter))}`,
    {
      headers: {
        'Authorization': apiKey,
        'Content-Type': 'application/json'
      }
    }
  );
  const { privacy_documents } = await response.json();

  // Replace each reference with corresponding document
  let resultText = text;
  allMatches.forEach(([fullMatch, templateKey, version]) => {
    const document = privacy_documents.find(
      doc => doc.template_key === templateKey.trim() && doc.version === Number(version)
    );

    if (document) {
      resultText = resultText.replace(
        fullMatch,
        `<a href="${escapeHtml(document.url)}" target="_blank" rel="noopener noreferrer">${escapeHtml(document.name)}</a>`
      );
    }
  });

  return resultText;
}

const consentText = "Acepto los {{ terms_and_conditions:1 }} y la {{ privacy_policy:2 }}";
const processedHTML = await processPrivacyDocuments(
  consentText,
  'https://api.soyio.id',
  'your-api-key'
);

Flexibilidad en la implementación

Las funciones de procesamiento mostradas arriba son la forma en que lo implementamos en nuestro SDK, pero tienes la libertad de presentar esta información de manera diferente según las necesidades de tu interfaz. Por ejemplo, podrías:

Consolidar todos los documentos de privacidad en una sección al final del texto de consentimiento y mostrar solo los nombres en el texto principal
Presentar los tooltips como notas al pie en lugar de elementos interactivos
Usar iconos o indicadores visuales personalizados para las referencias a documentos

Sea cual sea el enfoque que elijas, te recomendamos encarecidamente presentar toda la información al usuario de una forma u otra, para garantizar la transparencia y el cumplimiento normativo.

3. Crea el token de acción

Cuando el usuario otorga el consentimiento en tu interfaz, crea inmediatamente un token de acción usando el endpoint de creación de tokens de acción.

Importante: Para una trazabilidad adecuada, incluye información contextual en action_data y contextual_data:

POST /api/v1/consent_templates/{id}/action_tokens
{
    "context": "onboarding-producto-a",
    "kind": "grant",
    "action_type": "opt_in_click",
    "timestamp": "2024-03-20T15:30:00Z",
    "action_data": {
        "session_id": "sess_123456789",
        "internal_user_id": "user_12345",
        "campaign_id": "campaign_abc123",
        "page_section": "newsletter_signup",
        "form_step": "step_2"
    },
    "contextual_data": {
        "ip": "192.168.1.100",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "url": "https://tu-sitio.com/consent"
    }
}

La respuesta incluye el action_token que necesitas para crear el registro de consentimiento:

Respuesta
{
    "action_token": "<generated_action_token>"
}

Información

Si quieres registrar una revocación de consentimiento sin SDK, usa el endpoint de creación de acción de consentimiento con el kind seteado a revoke.

4. Crea el registro de consentimiento

Una vez que el usuario haya otorgado su(s) consentimiento(s) y tengas el action_token, crea el registro de consentimiento mediante el endpoint de creación de acción de consentimiento, incluyendo la información contextual del método de captura. Opcionalmente, puedes agregar el user_reference para asociar el consentimiento con un usuario específico de tu sistema.

Importante: Para una trazabilidad completa, incluye información detallada en consent_method:

POST /api/v1/consent_actions
{
    "action_token": "<action_token_from_step_3>",
    "user_reference": "user_12345",
    "consent_method": {
        "channel": "website",
        "capture_source": "TuSistemaInterno",
        "metadata": {
            "device_fingerprint": "fp_xyz789",
            "consent_version": "v1.2",
            "details": "El usuario otorgó consentimiento mediante checkbox en formulario de registro",
            "form_id": "registration_form_001",
            "campaign_source": "google_ads",
            "utm_campaign": "summer_promotion_2024",
            "user_flow_step": "registration_step_2"
        }
    }
}

También puedes crear un consent commits si quieres registrar varios consentimientos en una misma transacción. Revisa la guía de registro agrupado de consentimientos para más información.

Mejores prácticas para trazabilidad

Para garantizar una trazabilidad adecuada cuando usas la API directamente, te recomendamos incluir la mayor cantidad de información contextual posible en dos lugares diferentes:

Evita información personal identificable (PII)

No incluyas datos personales identificables (PII) como nombres completos, emails, números de teléfono completos, o cualquier información que pueda identificar directamente a una persona en los campos de trazabilidad. Usa identificadores internos o datos anonimizados en su lugar.

1. En la creación del action token

Al crear el action token, te recomendamos incluir información contextual en los campos action_data y contextual_data:

POST /api/v1/consent_templates/{id}/action_tokens
{
    "context": "onboarding-producto-a",
    "kind": "grant",
    "action_type": "opt_in_click",
    "timestamp": "2024-03-20T15:30:00Z",
    "action_data": {
        "session_id": "sess_123456789",
        "internal_user_id": "user_12345",
        "campaign_id": "campaign_abc123",
        "page_section": "newsletter_signup",
        "form_step": "step_2"
    },
    "contextual_data": {
        "ip": "192.168.1.100",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "url": "https://tu-sitio.com/consent"
    }
}

Al crear el consent action, te recomendamos incluir información del método de captura en consent_method:

POST /api/v1/consent_actions
{
    "action_token": "<action_token_from_step_3>",
    "user_reference": "user_12345",
    "consent_method": {
        "channel": "website",
        "capture_source": "TuSistemaInterno",
        "metadata": {
            "device_fingerprint": "fp_xyz789",
            "consent_version": "v1.2",
            "details": "El usuario otorgó consentimiento mediante checkbox en formulario de registro",
            "form_id": "registration_form_001",
            "campaign_source": "google_ads",
            "utm_campaign": "summer_promotion_2024",
            "user_flow_step": "registration_step_2"
        }
    }
}

Recomendaciones generales

Incluye la mayor cantidad de información contextual posible en ambos endpoints:
- En action_data y contextual_data del action token: datos específicos de la acción del usuario
- En consent_method.metadata del consent action: información del método de captura y contexto legal
Mantén logs detallados de las interacciones del usuario en tu sistema
Implementa un sistema de auditoría que permita rastrear cada acción de consentimiento
Documenta tu proceso de captura de consentimiento para auditorías futuras
Usa identificadores únicos en action_data para facilitar la búsqueda posterior de evidencia
Evita PII en los campos de trazabilidad - usa identificadores internos o datos anonimizados

Trazabilidad y Responsabilidad​

Detalles de cada enfoque​

Con SDK de Soyio​

Con integración directa vía API​

Pre-requisitos​

Paso a paso​

1. Crea o selecciona una plantilla de consentimiento​

2. Implementa tu propia lógica de consentimiento​

Obtén información de la plantilla​

Ventajas de usar la plantilla para generar tu UI​

Manejo de texto formateado en las cláusulas​

3. Crea el token de acción​

4. Crea el registro de consentimiento​

Mejores prácticas para trazabilidad​

1. En la creación del action token​

2. En la creación del consent action​

Recomendaciones generales​