# 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:

```mermaid
sequenceDiagram
participant frontend as Frontend
participant backend as Backend
participant soyio_api as Soyio API
participant soyio_widget as Soyio Widget
backend->>soyio_api: Crear disclosure request
soyio_api->>backend: Retorna ID de disclosure request
backend->>frontend: Retorna ID de disclosure request
frontend->>soyio_widget: Iniciar widget con configuración o `disclosure_request_id`
soyio_widget-->>frontend: Evento `WIDGET_OPENED`
soyio_widget->>soyio_widget: El usuario completa el flujo
soyio_widget-->>frontend: Evento `DISCLOSURE_REQUEST_SUCCESSFUL`
soyio_api-->>backend: Webhook: `disclosure_request.granted`
backend->>soyio_api: Obtener datos de identidad
soyio_api->>backend: Retorna información de identidad
```

### Prerrequisitos

1.  Tener el [SDK](https://docs.soyio.id/docs/integration-guide/intro) instalado en tu sitio o aplicación.
2.  Tener un [Webhook](https://docs.soyio.id/docs/api/webhooks) 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](https://docs.soyio.id/docs/integration-guide/disclosure/disclosure_templates) 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](#4-inicia-el-widget-desde-el-front-end).
    

> **tip**
> ¿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.

> **danger**
> 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](https://docs.soyio.id/docs/api/resources/create-disclosure-request) 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](https://docs.soyio.id/docs/api/resources/schemas/disclosurerequest).

```
{    "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        }    ]}
```

> **tip**
> Si necesitas revisar todos los campos y validaciones, consulta [Crear un disclosure request](https://docs.soyio.id/docs/api/resources/create-disclosure-request).
> **warning**
> 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.

> **warning**
> 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](https://docs.soyio.id/docs/integration-guide/disclosure/embedded-disclosure), donde encontrarás implementación con `DisclosureRequestBox` y consideraciones para passkeys.

> **info**
> Revisa la [guía de compatibilidad de dispositivos](https://docs.soyio.id/docs/integration-guide/disclosure/device-compatibility) 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ónconst 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 widgetfunction initWidget() {    new SoyioWidget(widgetConfig);}// Añade un escuchador de eventos al botón para inicializar el widget al hacer clicdocument    .getElementById("start-disclosure-request")    .addEventListener("click", initWidget);</script>
```

> **warning**
> 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ónconst 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 consentimientoconst initDisclosureRequest = () => {    disclosure(disclosureParams);};// Botón para iniciar el procesoreturn (    <View>    <Button title="Disclosure request" onPress={initDisclosureRequest} />    </View>);}
```

> **warning**
> 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.

> **note**
> Para más detalles sobre la configuración revisa las instrucciones del `Readme` del respectivo SDK:
> 
> -   [SDK Web](https://www.npmjs.com/package/@soyio/soyio-widget).
> -   [SDK Mobile](https://www.npmjs.com/package/@soyio/soyio-rn-sdk).

### 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. Encuentra todos los eventos que emite Soyio, con su payload, en el [catálogo de eventos](https://docs.soyio.id/docs/api/events):

**SDK Web**

| Evento | Descripción |
| --- | --- |
| `DISCLOSURE_REQUEST_SUCCESSFUL` | El usuario completó exitosamente el proceso de disclosure. |
| `WIDGET_CLOSED` | Se intenta emitir en `beforeunload`; no es fiable como señal de cierre. |
| `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. |

> **warning**
> Si integras el **popup del SDK web** dentro de un **WebView o shell nativo**, el host debe cerrar la ventana hija al terminar el flujo. Revisa [Integraciones dentro de un WebView o shell nativo](https://docs.soyio.id/docs/integration-guide/authentication/authenticate-users#integraciones-dentro-de-un-webview-o-shell-nativo).
> **note**
> Para más detalles sobre los eventos revisa las instrucciones del `Readme` del respectivo SDK:
> 
> -   [SDK Web](https://www.npmjs.com/package/@soyio/soyio-widget).
> -   [SDK Mobile](https://www.npmjs.com/package/@soyio/soyio-rn-sdk).

### 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](https://docs.soyio.id/docs/api/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](https://docs.soyio.id/docs/api/resources/get-identity).

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

> **info**
> 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](https://docs.soyio.id/docs/integration-guide/disclosure/disclosure-error-handling).

### 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](https://docs.soyio.id/docs/api/resources/get-identity).

### 8\. Consulta el agreement creado

Utiliza el `agreement_id` para consultar el agreement creado por tu usuario desde el [endpoint de agreements](https://docs.soyio.id/docs/api/resources/get-agreement).

## 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](https://docs.soyio.id/docs/integration-guide/disclosure/configuration) para ver opciones de personalización y configuración avanzada.