Saltar al contenido principal

Inicio rápido

Inicio rápido

Esta guía te ayudará a comenzar con la integración de Soyio en tu aplicación. Soyio ofrece tres módulos principales:

  • Disclosure: Revelación de datos y consentimiento
  • Signature: Firma de documentos
  • Authentication: Autenticación de usuarios

Pre-requisitos​

  1. Una cuenta de Soyio. Si no tienes una cuenta, contacta a nuestro equipo a soporte@soyio.id.
  2. Credenciales de API
  3. Un Webhook configurado en tu cuenta

Ambiente de pruebas​

Soyio proporciona un ambiente sandbox para desarrollo y pruebas, el cual puedes usar para probar tu integración antes de ir a producción.

Base URL: https://sandbox.soyio.id

El ambiente de pruebas no genera solicitudes reales, por lo que no se generarán documentos firmados, consentimientos, ni se realizarán verificaciones de identidad reales.

Revisa más información en nuestra guía de sandbox.

Instala el SDK​

Soyio proporciona SDKs para diferentes plataformas que facilitan la integración con nuestros servicios. Puedes instalar el SDK que mejor se adapte a tus necesidades usando npm:

npm install @soyio/soyio-widget

Crea tu primera solicitud de Disclosure​

El siguiente ejemplo muestra cómo implementar una solicitud de revelación de datos hacia el usuario usando el método recomendado (creación desde backend con matchers).

Antes de crear una solicitud de disclosure, necesitas una plantilla de disclosure. Aprende a crear una en nuestra guía de plantillas.

Método recomendado: Backend con matchers​

  1. Crea una solicitud de disclosure desde tu backend con matchers para prevención de fraude:
const response = await fetch('https://sandbox.soyio.id/api/v1/disclosure_requests', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    disclosure_template_id: "dtpl_...",
    user_reference: "user_123",
    user_email: "user@example.com",
    matchers: [
      { key: "cl_carnet_rut", value: "12345678-9" },
      { key: "name", value: "Juan" },
      { key: "last_name", value: "Perez" }
    ]
  })
});
const { disclosure_request_id } = await response.json();
  1. Inicia el widget en tu frontend con el disclosure_request_id obtenido:
import { SoyioWidget } from "@soyio/soyio-widget";

const widgetConfig = {
  request: "disclosure",
  configProps: {
    disclosureRequestId: disclosure_request_id
  },
  onEvent: (event) => {
    switch(event.type) {
      case 'DISCLOSURE_REQUEST_SUCCESSFUL':
        console.log('¡Proceso completado!');
        break;
      case 'WIDGET_CLOSED':
        console.log('Widget cerrado');
        break;
    }
  }
};

new SoyioWidget(widgetConfig);
¿Quieres integrarlo dentro de tu página?

También puedes usar el flujo embebido con DisclosureRequestBox.

Revisa la guía completa: Valida una identidad en modo embebido.

¿Por qué usar matchers?

Los matchers validan que la identidad verificada corresponda a los datos que el usuario ya registró en tu sistema, previniendo fraudes como:

  • Crear una cuenta con datos de una persona diferente a la que completó la validación
  • Completar la validación de identidad usando la cara y los documentos reales pero de otra persona
  • Obtener acceso no autorizado a servicios o realizar transacciones fraudulentas

Recomendación: Incluye todos los datos que tengas del usuario (RUT, nombre, apellido, fecha de nacimiento) para maximizar la protección. Aprende más sobre match de datos.

Método alternativo: Frontend sin matchers​

Si tienes un caso de uso de bajo riesgo y no necesitas validar contra datos existentes, puedes crear el disclosure request directamente desde el frontend:

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

const widgetConfig = {
  request: "disclosure",
  configProps: {
    companyId: "your_company_id",
    userReference: "user_123",
    userEmail: "user@example.com",
    templateId: "dtpl_..."
  },
  onEvent: (event) => {
    switch(event.type) {
      case 'DISCLOSURE_REQUEST_SUCCESSFUL':
        console.log('¡Proceso completado!');
        break;
      case 'WIDGET_CLOSED':
        console.log('Widget cerrado');
        break;
    }
  }
};

new SoyioWidget(widgetConfig);
Sin protección de matchers

Esta opción no permite usar matchers para validación de datos. Solo usa este método si tu caso de uso tiene bajo riesgo de fraude.

¿Necesitas ayuda?​

Si encuentras algún problema durante la integración, puedes:

  • Contactar a nuestro equipo de soporte vía correo electrónico a soporte@soyio.id
  • Consultar nuestros canales de Slack