Saltar al contenido principal

Recibe solicitudes de derecho

Recibe solicitudes de derecho

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

Usa el componente Privacy Center del SDK de Soyio para integrar fácilmente el portal de recepción de solicitudes de derechos en tu sitio web, proporcionando a tus usuarios una interfaz intuitiva para enviar sus solicitudes.

Gestión de derechos example

Integración en modo público​

Usa este modo para proporcionar acceso universal a la gestión de derechos, tanto para usuarios registrados como para visitantes.

Características:

  • No requiere autenticación previa del usuario
  • Permite que cualquier usuario ejerza sus derechos
  • Incluye un paso de validación de identidad

Para integrar el Privacy Center en modo público, sigue la guía de inicio rápido.

Integración en modo autenticado​

Usa este modo para proporcionar acceso a la gestión de derechos a usuarios autenticados en tu aplicación.

Características:

  • Requiere que autentiques al usuario previamente en tu sistema
  • Utiliza tokens de sesión como medida de seguridad
  • No es necesario validar la identidad del usuario nuevamente

Para integrar el Privacy Center en modo autenticado, necesitas obtener un token de sesión usando la API de Soyio. Para obtener el token de sesión, debes proporcionar el entity_id de la entidad para la cual se generará el token.

Si todavía no tienes un entity_id para el usuario, créalo una vez desde tu backend con POST /api/v1/entities usando tu user_reference. Guarda el entity_id que responde Soyio para reutilizarlo en futuras sesiones autenticadas.

Flujo de inicialización​

Crea la entidad una sola vez​

Antes de pedir un token de sesión, tu backend debe conocer el entity_id del usuario. Si tu sistema todavía no lo tiene, crea una entidad con el identificador interno del usuario (user_reference) y guarda el entity_id que responde Soyio.

Ejecuta este paso solo cuando no tengas un entity_id guardado. POST /api/v1/entities no reemplaza entidades existentes: si ya hay una entidad con el mismo user_reference, la API responderá 422. En ese caso, reutiliza el entity_id guardado en tu sistema o consulta tus entidades por user_reference antes de reintentar la creación.

Backend - Asegurar entidad
const ensureEntityId = async (userReference) => {
  const storedEntityId = await findStoredSoyioEntityId(userReference);

  if (storedEntityId) {
    return storedEntityId;
  }

  const response = await fetch('https://api.soyio.id/api/v1/entities', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SOYIO_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      user_reference: userReference
    })
  });

  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(error.detail || `Error: ${response.status}`);
  }

  const data = await response.json();
  await saveStoredSoyioEntityId(userReference, data.entity.id);

  return data.entity.id;
};

Revisa la referencia del API para Crear una entidad y Obtener todas las entidades para más detalles.

Obtén el token de sesión​

Una vez que el usuario se ha autenticado en tu sistema, usa el endpoint GET /api/v1/privacy_center/session_token para obtener el token de sesión.

Envía entity_id como query param. Opcionalmente, envía config[cl_carnet_rut], config[names], config[last_names], config[email] y config[phone] para fijar el RUT, nombres, apellidos, correo y teléfono del usuario durante la sesión autenticada.

Backend - Obtener token de sesión
const getSessionToken = async (entityId, { rut, names, lastNames, email, phone } = {}) => {
  const url = new URL('https://api.soyio.id/api/v1/privacy_center/session_token');
  url.searchParams.append('entity_id', entityId);

  if (rut) url.searchParams.append('config[cl_carnet_rut]', rut);
  if (names) url.searchParams.append('config[names]', names);
  if (lastNames) url.searchParams.append('config[last_names]', lastNames);
  if (email) url.searchParams.append('config[email]', email);
  if (phone) url.searchParams.append('config[phone]', phone);

  const response = await fetch(url.toString(), {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${process.env.SOYIO_API_KEY}`
    }
  });

  if (!response.ok) {
    throw new Error(`Error: ${response.status}`);
  }

  const data = await response.json();
  return data.token;
};
Importante

Si generas el token con config[cl_carnet_rut], el campo RUT del formulario DSR queda prellenado y bloqueado en el Privacy Center. Al crear la solicitud, contact_information.nin debe coincidir con ese valor o la API responderá 422.

config[names], config[last_names], config[email] y config[phone] también prellenan y bloquean los campos correspondientes.

Si tu DSR usa solo verificación gubernamental (liveness_check: false, id_scan_check: false, government_check: true), este RUT prellenado también se usa en el paso de validación. El usuario solo debe ingresar el número de documento.

Revisa la referencia del API para Obtener un token de sesión para el centro de privacidad para más detalles.

Integra el componente en tu frontend​

Una vez que tengas el token de sesión, configura el Privacy Center usando el token de sesión.

js/privacy-center.js
import { PrivacyCenter } from "@soyio/soyio-widget";

const privacyCenterOptions = {
    sessionToken: "<session_token>", // Reemplaza con el token de sesión
    enabledFeatures: ['DataSubjectRequests', 'RequestTracking'],
    onEvent: (event) => {
        console.log('Evento del Privacy Center:', event);
        // Maneja los eventos según tus necesidades
    },
    onReady: () => {
        console.log('Privacy Center está listo');
    },
    appearance: {
        theme: 'soyio',
        variables: {
            colorPrimary: '#f54c27',
            colorBackground: '#ffffff'
        }
    },
    isSandbox: false
};

// Inicializa el Privacy Center
const privacyCenter = new PrivacyCenter(privacyCenterOptions);
privacyCenter.mount("#privacy-center-container");

Creación de la solicitud​

Cuando un usuario envía una solicitud de ejercicio de derechos, se creará un nuevo Data subject Request o DSR. Este recurso es el que mantendrá la trazabilidad de la solicitud y su estado a medida que se procese la solicitud.

Correlación con webhooks usando referencias​

Cada solicitud de ejercicio de derechos (DSR) puede incluir una referencia opcional (request_reference) que te permite correlacionar los webhooks y eventos que recibas de Soyio con tus propios sistemas de gestión.

¿Para qué sirve?​

El campo request_reference te permite:

  • Correlacionar webhooks: Identifica rápidamente a qué ticket, caso o registro de tu sistema corresponde cada notificación de webhook.
  • Seguimiento simplificado: Mantén la trazabilidad entre tu sistema interno y las solicitudes procesadas en Soyio.
  • Automatización eficiente: Facilita la integración programática con tus flujos de trabajo existentes.

Cómo usar la referencia con el SDK​

Cuando inicializas el Privacy Center, puedes pasar una referencia en las opciones principales. Esta referencia se asociará automáticamente a todas las solicitudes creadas desde ese componente:

Inicializar Privacy Center con referencia
import { PrivacyCenter } from "@soyio/soyio-widget";

// Obtén el identificador de tu sistema (ej: ID de ticket, usuario, sesión)
const userTicketId = "ticket-12345";

const privacyCenterOptions = {
  companyId: "<company_id>", // O usa sessionToken para modo autenticado
  enabledFeatures: ['DataSubjectRequests', 'RequestTracking'],
  requestReference: userTicketId,
  onEvent: (event) => {
    console.log('Evento del Privacy Center:', event);

    // Cuando se crea una solicitud, la referencia estará incluida
    if (event.type === 'data_subject_request.created') {
      console.log('Solicitud creada con referencia:', event.data.request_reference);
      // Actualiza tu sistema interno con el ID de Soyio
      updateInternalTicket(userTicketId, event.data.id);
    }
  }
};

const privacyCenter = new PrivacyCenter(privacyCenterOptions);
privacyCenter.mount("#privacy-center-container");
Uso directo de la API

También puedes incluir el campo request_reference al crear solicitudes directamente mediante la API de Soyio, especialmente útil cuando construyes tu propia interfaz personalizada o automatizas la creación de solicitudes desde tu backend.

Recibir la referencia en webhooks​

Cuando Soyio envíe webhooks sobre cambios en el estado de la solicitud, el campo request_reference estará incluido en la carga útil del evento:

Ejemplo de webhook con referencia
{
  "event": "data_subject_request.updated",
  "data": {
    "id": "dsr_abc123",
    "request_type": "access",
    "status": "processing",
    "request_reference": "ticket-12345",
    ...
  }
}

Esto te permite identificar inmediatamente el ticket o caso en tu sistema que corresponde a esta solicitud.

Buena práctica

Usa identificadores únicos y descriptivos como referencias (ej: ticket-12345, caso-CRM-789, solicitud-2024-001) para facilitar el debugging y el seguimiento.

Eventos del frontend para tracking en tiempo real​

Si necesitas reaccionar a lo que ocurre en el formulario de DSR sin esperar a los webhooks de backend, suscríbete al callback onEvent del Privacy Center. Los eventos relevantes para este flujo son:

  • REQUEST_SUBMITTED: el usuario envió la solicitud con éxito.
  • REQUEST_SUBMISSION_FAILED: el envío falló (error de red o backend).
  • VALIDATION_SUCCESSFUL: la validación de identidad asociada se completó.
  • VALIDATION_FAILED: la validación falló.

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

Siguientes pasos​