Revelación de datos y consentimiento (Disclosure)

Solicita a tus usuarios la revelación inicial de sus datos personales verificados.

Este módulo mejora tu proceso de onboarding para adaptarlo a las regulaciones más estrictas de protección de datos personales, permitiendote cumplir con la captura de consentimiento y la verificación de identidad.

A grandes rasgos, el módulo Disclosure te permite:

Verificar identidad: Confirma que tus usuarios son quienes dicen ser
Obtener consentimiento: Registra la autorización explícita para el uso de datos
Recolectar datos: Recibe información verificada de tus usuarios

El proceso de disclosure

El proceso de disclosure se compone de los siguientes pasos:

El usuario otorga su consentimiento para compartir datos
Se realiza la verificación de identidad
(Opcional) Se realiza un match entre los datos verificados y los datos almacenados en tu sistema.
Se crea una identidad verificada en el sistema
Se genera un Agreement con evidencia del proceso

info

Este módulo incluye la verificación de identidad de tu usuario. Puedes leer más detalles de cómo Soyio realiza la verificación en la documentación sobre verificación de identidad.

Descripción detallada

Este flujo comienza con la entrega de consentimiento. El usuario verá los datos que estás solicitando y deberá confirmar su consentimiento para continuar.

Luego, se verificará la identidad del usuario. Al completar este paso, se creará una identidad con los datos verificados, que podrás consultar utilizando la API de Soyio.

Al finalizar el proceso de entrega de datos y consentimiento, se creará un acuerdo (Agreement) y la evidencia asociada, que podrás utilizar para demostrar que el usuario otorgó su consentimiento libre, específico, inequívoco e informado.

Match de datos

Opcionalmente, si el usuario creó una cuenta en tu sistema previamente y entregó datos de identificación, puedes incluir como parte del proceso que Soyio verifique el match entre los datos verificados que el usuario entrega en este proceso y la información almacenada en tu sistema. Si ocupas esta opción y el match no es exitoso, el proceso concluye sin crear una identidad. Los campos disponibles para realizar el match son:

Campo	Descripción
`cl_carnet_rut`	RUT chileno (sin puntos y con guión)
`name`	Nombres del usuario (separados por un espacio y sin tildes)
`last_name`	Apellidos del usuario (separados por un espacio y sin tildes)
`date_of_birth`	Fecha de nacimiento del usuario (formato: `YYYY-MM-DD`)

Estados

Pending: Es el estado inicial de la solicitud. El proceso está listo para comenzar pero aún no se ha iniciado
Authenticating: El usuario registrado está en proceso de Autenticación
Awaiting Permissions: El sistema está esperando que el usuario otorgue los consentimientos necesarios. Se muestran los permisos y datos que se solicitan al usuario
Validating: Se están validando los datos proporcionados por el usuario. Se verifica que la información cumpla con los requisitos establecidos
Awaiting missing data: Se requiere información adicional del usuario. El sistema espera que el usuario complete los datos faltantes
Granted: El proceso se ha completado exitosamente. Se han validado los datos y obtenido los consentimientos necesarios
Timed Out: La solicitud ha expirado por inactividad. El proceso no se completó dentro del tiempo establecido
Failed: La solicitud ha fallado por que los datos no hacen match. Este chequeo solo ocurre cuando se realiza un match de datos. El proceso no se completó exitosamente.

Diagrama de estados

Integración

El flujo que integrarás es el siguiente:

Pre requisitos

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

Paso a paso

1. Crea una plantilla de disclosure

Para comenzar, deberás definor 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.

Aluunos 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 consentimiento y finalidades.

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 como incializar el flujo de disclosure en nuestros SDKs:

SDK Web
SDK Mobile

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>

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
SDK Mobile

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.

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 relacionados al flujo principal son los relacionados al recurso de disclosure request y tienen el prefijo de disclosure_request..

Disclosure request exitoso
Disclosure request caducado
Disclosure request fallido (error en el match)

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

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

{
    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 Autenticación

Validación exitosa
{
    id: "evt_...",
    name: "validation_attempt.successful",
    payload: {
        user_reference: "<user-reference>",
        validation_attempt_id: "va_...",
        identity_id: "id_..."
    },
    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>"
}

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.

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: "validation_error".

El proceso de disclosure​

Descripción detallada​

Match de datos​

Estados​

Integración​

Pre requisitos​

Paso a paso​

1. Crea una plantilla de disclosure​

2. Crea una solicitud de disclosure​

3. Crea el proceso desde el backend (opcional)​

Endpoint​

Ejemplo del Payload​

4. Inicia el proceso desde el front-end​

Ejemplos​

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

6. Escucha los eventos en el back-end de tu aplicación​

Errores en la validación​

Errores de validación de identidad​

Errores de documento​

Errores de imagen​

Errores de validación facial​

Errores de validación con base de datos gubernamental​

Errores de edad​

Errores técnicos​

7. Consulta los datos de la identidad creada​

Prueba tu integración​