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

Para comenzar, deberás definir qué datos necesitas solicitar a tus usuarios de forma obligatoria para que puedan continuar con el proceso en tu empresa. Para ello, identifica la finalidad que tendrá cada uno de estos datos y por cuánto tiempo los almacenarás.

Luego, envía la información vía Slack y te haremos llegar el id de la plantilla (disclosure_template_id) que utilizarás en el próximo paso.

Algunos ejemplos de finalidades son:

• Gestión de clientes: Para el registro, mantenimiento y soporte de clientes.
• Marketing: Envío de comunicaciones promocionales, boletines informativos y ofertas personalizadas.
• Recursos Humanos: Para la administración del personal, procesos de selección y evaluaciones de desempeño.
• Mejora del servicio: Análisis de datos de uso para optimizar productos y servicios.
• Cumplimiento legal: Mantener registros conforme a las normativas y responder a solicitudes legales.
• Ciberseguridad: protección contra accesos no autorizados o actividades fraudulentas.

Información

Si tu empresa no tiene una definición específica en sus políticas contáctanos para ayudarte a determinarlas adecuadamente. Profundiza en estos conceptos revisando nuestra documentación sobre la taxonomía.

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 mas detalles en la documentación de nuestros SDKs.

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.

Los eventos que puedes escuchar son:

• disclosure_request.granted: El usuario completa exitosamente el disclosure
• disclosure_request.timed_out: El usuario no completa el disclosure en el tiempo permitido
• disclosure_request.failed: El disclosure falla por alguna razón de la que no se puede recuperar

A medida que el usuario avanza en el flujo, estos eventos se enviarán mediante webhooks para representar cambios en el estado del proceso y sus objetos asociados.

Disclosure request exitoso

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

Disclosure request caducado

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

Disclosure request fallido (error en el match)

{
    id: "evt_...",
    name: "disclosure_request.failed",
    payload: {
        user_reference: "<user-reference>",
        disclosure_request_id: "dreq_...",
    },
}

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.

Adicionalmente, puedes escuchar eventos del proceso de verificación de identidad, que se lleva a cabo durante el disclosure, para obtener detalles adicionales sobre la validación y autenticación.

Estos eventos pueden incluir información sobre errores en el proceso de verificación, como fallos en la autenticación o problemas al validar datos de identidad.

Además, siempre que se emita un evento disclosure_request.granted, también recibirás un evento correspondiente de validación o autenticación exitosa, lo que indica que el proceso ha concluido satisfactoriamente.

Eventos de Validación

Eventos de webhooks disponibles:

• validation_attempt.successful: La validación de identidad fue exitosa.
• validation_attempt.failed: La validación de identidad falló, pero puede recuperarse.

Validación exitosa

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

Validación fallida

{
    id: "evt_...",
    name: "validation_attempt.failed",
    payload: {
        user_reference: "<user-reference>",
        validation_attempt_id: "va_...",
        error_reason: "passive_liveness_verification_not_passed",
        errors_array: [
        {
            code: "auth-XXX",
            type: "facial",
            message: "passive_liveness_verification_not_passed",
            detail: "La verificación de vivacidad pasiva no fue exitosa."
        },
        ...
        ]
    },
    created_at: "<created_at>"
}

Eventos de Autenticación

Eventos de webhooks disponibles:

• auth_attempt.successful: La autenticación fue exitosa.
• auth_attempt.failed: La autenticación falló, pero puede recuperarse.

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>"
}

Autenticación fallida

{
    id: "evt_...",
    name: "auth_attempt.failed",
    payload: {
        user_reference: "<user-reference>",
        auth_attempt_id: "aa_...",
        error_reason: "passive_liveness_verification_not_passed",
        errors_array: [
        {
            code: "auth-XXX",
            type: "facial",
            message: "passive_liveness_verification_not_passed",
            detail: "La verificación de vivacidad pasiva no fue exitosa."
        },
        ...
        ]
    },
    created_at: "<created_at>"
}

Errores en la validación

Para las validaciones fallidas, los errores (descritos en el campo error_reason) que puedes recibir son los siguientes:

Errores de validación

Errores de validación de identidad

• unknown: Error desconocido.

Errores de documento

• document_validation_error: Error en la validación del documento.
• document_has_expired: El documento expiró.
• document_not_recognized: El documento no fue reconocido.
• document_unregistered: El documento no está registrado.
• damaged_document: El documento está dañado.
• document_is_a_photo_of_photo: Error en la imagen.
• document_is_a_photocopy: El documento es una copia.
• incomplete_document: El documento es incompleto.
• invalid_issue_date: La fecha de emisión es inválida.
• missing_date_of_birth: Falta la fecha de nacimiento.
• missing_document_number: Falta el número del documento.
• missing_expiration_date: Falta la fecha de expiración.
• missing_gender: Falta el género.
• missing_mrz: Falta el MRZ.
• missing_names: Falta los nombres.
• missing_text: Falta el texto.
• missing_issue_date: Falta la fecha de emisión.
• missing_nationality: Falta la nacionalidad.

Errores de imagen

• blurry_image: La imagen es borrosa.
• front_document_not_found: No se encontró la imagen frontal del documento.
• invalid_or_corrupted_image_file: La imagen es inválida o está corrupta.
• photo_of_photo: La imagen es de una foto de una foto.
• reverse_document_not_found: No se encontró la imagen inversa.
• image_validation_not_passed: No pasó la validación de la imagen.

Errores de validación facial

• facial_validation_error: Error en la validación facial.
• fraudster_face_match_in_client_collection: La coincidencia de rostro es de un fraude.
• liveness_verification_not_passed: La verificación de vivacidad no fue exitosa.
• no_face_detected: No se detectó rostro.
• passive_liveness_verification_not_passed: La verificación de vivacidad pasiva no fue exitosa.
• similarity_threshold_not_passed: No pasó el umbral de similitud.
• face_not_clear: El rostro no es claro.
• face_not_detected: No se detectó rostro.

Errores de validación con base de datos gubernamental

• data_not_match_with_government_database: Los datos no coinciden con la base de datos del gobierno.
• government_database_unavailable: La base de datos del gobierno no está disponible.
• identity_belongs_to_dead_person: La identidad del usuario pertenece a una persona fallecida.

Errores de edad

• age_above_threshold: El usuario es mayor a la edad máxima permitida.
• underage: El usuario es menor de edad.

Errores técnicos

• ocr_no_text_detected: No se detectó texto.
• expiration_error: La validación expiró.
• enrollment: El usuario falló al inscribirse.
• camera_permission_error: No se tiene permiso para usar la cámara.
• invalid_format: El formato es inválido.
• possible_fraud: Es posible que sea fraude.
• validations_failed: Error en las validaciones.

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.

9. Prueba tu integración

Para probar tu integración, en ambiente de pruebas (Sandbox) puedes utilizar el parámetro force_error en el payload de la solicitud de disclosure, tanto en el backend como en el frontend. Por ejemplo, puedes simular una validación fallida pasando force_error: "document_validation_error".

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.