Valida una identidad obteniendo datos

Valida una identidad obteniendo datos

Aprende a integrar el módulo de verificación de identidad para solicitar datos personales verificados a tus usuarios.

Integración

El flujo que integrarás es el siguiente:

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Prerrequisitos

1. Tener el SDK instalado en tu sitio o aplicación.
2. Tener un Webhook configurado en tu cuenta.

Paso a paso

1. Crea una plantilla de disclosure

Antes de integrar el proceso de verificación de identidad, necesitas crear una plantilla que defina qué datos solicitar a tus usuarios. Sigue nuestra guía de plantillas para configurar tu plantilla de disclosure. Una vez creada, obtendrás el disclosure_template_id que utilizarás en el próximo paso.

2. Crea una solicitud de disclosure

Soyio soporta dos formas de crear el proceso de entrega de datos y consentimiento (disclosure):

• Desde el backend (Recomendado): Crea la solicitud desde tu servidor para acceder a la funcionalidad de match de datos, crítica para la prevención de fraude. Esta es la forma recomendada para la mayoría de las integraciones, especialmente en plataformas de comercio.

• Desde el frontend (Alternativa): Crea la solicitud directamente desde tu aplicación cliente a través de nuestro SDK. Esta opción es útil para casos de uso específicos donde no necesitas validación de datos previos o tienes un modelo de negocio de bajo riesgo de fraude. Si deseas usar esta opción, salta al paso 4.

¿Cuál método debo usar?

• Usa backend si: operas un comercio, necesitas validar identidad contra datos existentes, manejas transacciones financieras, o requieres alta seguridad
• Usa frontend si: tienes un caso de uso de bajo riesgo, no tienes datos previos del usuario, o necesitas un flujo más simple sin backend

3. Crea el proceso desde el backend

Este es el método recomendado para la mayoría de las integraciones. Crear el disclosure request desde tu backend te permite utilizar los matchers, una capa crítica de seguridad que valida que los datos verificados coincidan con los datos que el usuario ya registró en tu sistema.

Prevención de fraude con matchers

Los matchers previenen 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

Sin matchers, estás expuesto a riesgos significativos de fraude. Esta funcionalidad solo está disponible al crear el disclosure request desde el backend.

Para crear el proceso desde el backend, realiza una solicitud POST al endpoint de disclosure requests de Soyio. Esto creará una solicitud de disclosure y obtendrás un disclosure_request_id, que utilizarás en el siguiente paso.

Endpoint

POST /api/v1/disclosure_requests

Ejemplo del Payload

Inicia el proceso indicando el disclosure_template_id de la plantilla creada (el que comienza con dtpl_...) y los matchers con los datos que deseas validar. Puedes revisar más detalles en la documentación de la API.

{
    "disclosure_template_id": "dtpl_...",
    "user_reference": "<identificador de usuario de la empresa>",
    "user_email": "<email del usuario>",
    "matchers": [ // Validación crítica para prevención de fraude
        {
        "key": "cl_carnet_rut",
        "value": "12345678-9" // sin puntos y con guión
        }
    ]
}

Si necesitas revisar todos los campos y validaciones, consulta Crear un disclosure request.

Configuración de matchers

Recomendación: Incluye todos los datos disponibles que el usuario proporcionó al registrarse (RUT, nombre, apellido, fecha de nacimiento). Esto maximiza la protección contra fraude.

El match es exitoso si todos los datos coinciden. Si algún dato no coincide, el proceso de disclosure se detendrá y no se creará una identidad, protegiendo tu plataforma de intentos fraudulentos.

Para hacer match de múltiples datos, agrega más objetos al array matchers:

"matchers": [
  { "key": "cl_carnet_rut", "value": "12345678-9" },
  { "key": "name", "value": "Juan" },
  { "key": "last_name", "value": "Perez" },
  { "key": "date_of_birth", "value": "1990-01-15" }
]

4. Inicia el widget desde el front-end

Una vez que hayas creado el disclosure request (desde el backend en el paso 3, o directamente desde el frontend como se muestra más abajo), inicia el widget de Soyio en tu aplicación para que el usuario complete el proceso de verificación.

Para evitar que el navegador bloquee el popup, asegúrate de que el widget se inicialice solo a través de una interacción directa del usuario, como un clic, debido a las políticas de seguridad del navegador contra ventanas emergentes. Revisa más detalles en la documentación de nuestros SDKs.

Modalidad de integración: Popup vs modo embebido

• Popup (SoyioWidget): recomendado para la mayoría de integraciones web. Es la modalidad base de esta guía.
• Modo embebido (DisclosureRequestBox): recomendado cuando necesitas mantener el flujo dentro de la UI de tu aplicación.

Para modo embebido, revisa Valida una identidad en modo embebido, donde encontrarás implementación con DisclosureRequestBox y consideraciones para passkeys.

Revisa la guía de compatibilidad de dispositivos para conocer los dispositivos y navegadores soportados, mensajes de fallback y expectativas de soporte.

Ejemplos

A continuación te dejamos ejemplos de cómo inicializar el flujo de disclosure en nuestros SDKs:

SDK Web

Con disclosure request creado en backend (Recomendado)

<button id="start-disclosure-request">Start disclosure request</button>

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

    // Configuración
    const widgetConfig = {
        request: "disclosure",
        configProps: {
            disclosureRequestId: "<disclosure_request_id>",
        },
        onEvent: (data) => console.log(data)
    };

    // Creación del widget
    function initWidget() {
        new SoyioWidget(widgetConfig);
    }

    // Añade un escuchador de eventos al botón para inicializar el widget al hacer clic
    document
        .getElementById("start-disclosure-request")
        .addEventListener("click", initWidget);
</script>

Con disclosure request creado en frontend (Alternativa sin matchers)

<button id="start-disclosure-request">Start disclosure request</button>

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

// Configuración
const widgetConfig = {
    request: "disclosure",
    configProps: {
        companyId: "<company id>",
        userReference: "<user identifier of company>",
        userEmail: "<user email>",
        templateId: "<template id>",
    },
    onEvent: (data) => console.log(data),
};

// Creación del widget
function initWidget() {
    new SoyioWidget(widgetConfig);
}

// Añade un escuchador de eventos al botón para inicializar el widget al hacer clic
document
    .getElementById("start-disclosure-request")
    .addEventListener("click", initWidget);
</script>

Sin protección de matchers

Al crear el disclosure request desde el frontend, no podrás usar matchers para validar los datos. Esta opción es adecuada solo para casos de uso de bajo riesgo de fraude.

SDK Mobile

Con disclosure request creado en backend (Recomendado)

import { useSoyioAuth } from "@soyio/soyio-rn-sdk";

export default function App() {

    // Configuración
    const options = {
        uriScheme: "<company custom uri scheme>"
    };

    const disclosureParams = {
        disclosureRequestId: "<disclosure_request_id>"
    };

    const onEventChange = (event) => {
        console.log("Event:", event);
    };

    const { disclosure } = useSoyioAuth({ options, onEventChange });

    // Inicia el proceso de entrega de datos y consentimiento
    const initDisclosureRequest = () => {
        disclosure(disclosureParams);
    };

    // Botón para iniciar el proceso
    return (
        <View>
        <Button title="Disclosure request" onPress={initDisclosureRequest} />
        </View>
    );
}

Con disclosure request creado en frontend (Alternativa sin matchers)

import { useSoyioAuth } from "@soyio/soyio-rn-sdk";

export default function App() {

// Configuración
const options = {
    companyId: "<company id>",
    uriScheme: "<company custom uri scheme>",
    userReference: "<company identifier of user>",
};

const disclosureParams = {
    templateId: "<template id>",
    userEmail: "<user email>",
};

const onEventChange = (event) => {
    console.log("Event:", event);
};

const { disclosure } = useSoyioAuth({ options, onEventChange });

// Inicia el proceso de entrega de datos y consentimiento
const initDisclosureRequest = () => {
    disclosure(disclosureParams);
};

// Botón para iniciar el proceso
return (
    <View>
    <Button title="Disclosure request" onPress={initDisclosureRequest} />
    </View>
);
}

Sin protección de matchers

Al crear el disclosure request desde el frontend, no podrás usar matchers para validar los datos. Esta opción es adecuada solo para casos de uso de bajo riesgo de fraude.

Para más detalles sobre la configuración revisa las instrucciones del Readme del respectivo SDK:

• SDK Web.
• SDK Mobile.

5. Escucha los eventos en el front-end de tu aplicación

A medida que el usuario completa el flujo, se emitirán eventos que informan sobre el estado del proceso. Según el caso, tu sistema deberá manejarlos. Cuando el usuario complete el proceso exitosamente se emitirá el evento DISCLOSURE_REQUEST_SUCCESSFUL.

A continuación te detallamos los eventos que puedes escuchar:

SDK Web

Evento	Descripción
DISCLOSURE_REQUEST_SUCCESSFUL	El usuario completó exitosamente el proceso de disclosure.
WIDGET_CLOSED	El usuario cierra el popup de Soyio.
WIDGET_OPENED	El usuario abre el popup de Soyio.
UNEXPECTED_ERROR	Ocurrió un error inesperado en el proceso de disclosure.

SDK Mobile

Evento	Descripción
success	El usuario completó exitosamente el proceso de disclosure.
open_disclosure	El usuario abre el webview.
cancel	El usuario cierra el webview.
error	El usuario sale debido a un error.

Para más detalles sobre los eventos revisa las instrucciones del Readme del respectivo SDK:

• SDK Web.
• SDK Mobile.

6. Escucha los eventos en el backend de tu aplicación

Al igual que en el frontend, a medida que el usuario avanza en el flujo se enviarán varios eventos mediante webhooks, que representan cambios en el estado del proceso y sus objetos asociados.

Eventos de éxito

El evento que determina que un disclosure se completó con éxito es disclosure_request.granted. En él encontrarás el identity_id de la identidad creada, con el cual podrás consultar la información de la identidad en el endpoint de identidades.

{
    id: "evt_...",
    name: "disclosure_request.granted",
    payload: {
        user_reference: "<user-reference>",
        disclosure_request_id: "dreq_...",
        identity_id: "id_..."
    },
    created_at: "<created_at>"
}

Eventos de validación y autenticación exitosos

Adicionalmente, puedes escuchar eventos del proceso de verificación de identidad que indican éxito:

• validation_attempt.successful: La validación de identidad fue exitosa
• auth_attempt.successful: La autenticación fue exitosa

Validación exitosa

{
    id: "evt_...",
    name: "validation_attempt.successful",
    payload: {
        user_reference: "<user-reference>",
        validation_attempt_id: "va_...",
    },
    created_at: "<created_at>"
}

Autenticación exitosa

{
    id: "evt_...",
    name: "auth_attempt.successful",
    payload: {
        user_reference: "<user-reference>",
        auth_attempt_id: "aa_...",
        identity_id: "id_..."
    },
    created_at: "<created_at>"
}

Para información detallada sobre el manejo de errores, eventos de error y códigos de error específicos, consulta nuestra guía de manejo de errores.

7. Consulta los datos de la identidad creada

Utiliza el identity_id para consultar la identidad creada por tu usuario desde el endpoint de identidades.

8. Consulta el agreement creado

Utiliza el agreement_id para consultar el agreement creado por tu usuario desde el endpoint de agreements.

Próximos pasos

¡Felicitaciones! Has completado la integración básica del módulo de Disclosure.

Para personalizar el comportamiento según las necesidades de tu empresa, consulta la Configuración del módulo de Disclosure para ver opciones de personalización y configuración avanzada.