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.

Pre requisitos

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 back-end: esta opción te permite acceder a la funcionalidad de match de parámetros.

• Desde el front-end: en esta opción te permite iniciar el proceso de manera flexible desde el front-end de tu aplicación a través de nuestro SDK, el cual se encargará de crear la solicitud de disclosure. Si deseas utilizar esta opción, salta este paso y avanza directamente al paso 4.

3. Crea el proceso desde el backend (opcional)

Para crear el proceso desde el backend realiza un POST request desde tu back-end 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_...) previamente y opcionalmente indica el o los datos con los que deseas hacer match. 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": [ // Comprobación del RUT (Opcional)
        {
        "key": "cl_carnet_rut",
        "value": "12345678-9" // sin puntos y con guión
        }
    ]
}

Pro Tip

Si deseas hacer match de más de un dato, agrega más objetos al array matchers. Considera que el match es exitoso si todos los datos coinciden. En caso contrario, el proceso de disclosure no se completará.

4. Inicia el proceso desde el front-end

Inicia el proceso de entrega de datos y consentimiento desde el front-end de tu aplicación utilizando el SDK de Soyio.

Importante

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.

Compatibilidad

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

Disclosure request creado en backend

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

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

    // Configuracion
    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>

Disclosure request que se crea en frontend

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

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

// Configuracion
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>

SDK Mobile

Disclosure request creado en backend

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>
    );
}

Disclosure request que se crea en frontend

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>
);
}

Detalles

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 completando el flujo se emitirán eventos, los cuales informarán sobre el estado del proceso, y dependiendo del caso, tu sistema deberá manejarlos. Cuando el usuario complete el proceso exitosamente se emitirá un evento de 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.

Detalles

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 back-end de tu aplicación

Al igual que en el front, 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 ha terminado con éxito es el de disclosure_request.granted. En el encontraras 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>"
}

Información sobre errores

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.

Tip

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.