> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuración de Biometría Webview

> Configura los outputs y personaliza las reglas, la marca y los mensajes de Biometría Webview.

## Outputs

### Éxito

<AccordionGroup>
  <Accordion title="Biometría Aprobada" icon="circle-check">
    Confirma que la verificación biométrica fue exitosa.

    **Variable:** `approved`

    **Descripción:** Biometría Aprobada

    **Estructura de respuesta (JSON):**

    ```json theme={null}
    {
      "document_response": {
        "document_check": {
          "result": "",
          "verified_fields": { "...": "Datos principales del documento" },
          "secondary_fields": { "...": "Datos secundarios del documento" },
          "details": { "...": "Detalles del tipo de documento" },
          "status_fields": { "...": "Estado de validaciones" },
          "image_quality_details": { "...": "Detalles de la calidad de la imagen" },
          "images_extracted": { "...": "Imágenes extraídas del documento" },
          "gov_entity_fields": { "document_number": "Número del documento de identidad" }
        },
        "document_image_front_url": "URL de la imagen frontal del documento",
        "document_image_back_url": "URL de la imagen posterior del documento",
        "document_face_image_url": "URL del rostro extraído del documento"
      },
      "liveness_response": {
        "result": "true",
        "url_selfie_image": "URL de la foto obtenida para validar vivacidad"
      },
      "facematch_response": {
        "facematch_result": "approved",
        "facematch_confidence": "Porcentaje de coincidencia (0-100)"
      },
      "reporte_de_biometria": {
        "report": "URL del reporte de biometría (web)",
        "report_pdf": "URL del reporte de biometría (PDF)"
      },
      "device_info": {
        "userAgent": "Cadena del agente de usuario",
        "browser": "Navegador",
        "operatingSystem": "Sistema operativo",
        "platform": "Plataforma del dispositivo",
        "language": "Idioma",
        "timezone": "Zona horaria",
        "screenResolution": "Resolución de pantalla",
        "colorDepth": "Profundidad de color en bits",
        "timestamp": "Marca de tiempo del dispositivo",
        "ipAddress": "Dirección IP",
        "location": {
          "latitude": "Latitud (si el usuario otorga permiso)",
          "longitude": "Longitud (si el usuario otorga permiso)"
        },
        "deviceId": "Identificador único del dispositivo",
        "deviceName": "Nombre del dispositivo"
      },
      "gov_entity_data": {
        "...": "Datos de la entidad gubernamental del país (varía según el país)"
      }
    }
    ```

    **Campos importantes:**

    * `document_response`: Información del documento de identidad
    * `liveness_response`: Foto enviada para validar la prueba de vida
    * `facematch_response`: Resultado de la comparación facial
    * `reporte_de_biometria`: URLs del reporte en formato web y PDF
    * `device_info`: Datos de dispositivo y ubicación (auditoría y trazabilidad)
    * `gov_entity_data`: Datos de la entidad gubernamental (si aplica)

    **Definición de variables del JSON response:**

    * **document\_response:** `document_check` (result, verified\_fields, secondary\_fields, details, status\_fields, image\_quality\_details, images\_extracted, gov\_entity\_fields), `document_image_front_url`, `document_image_back_url`, `document_face_image_url`
    * **liveness\_response:** `result`, `url_selfie_image`
    * **facematch\_response:** `facematch_result` (approved/decline), `facematch_confidence`
    * **reporte\_de\_biometria:** `report`, `report_pdf`
    * **device\_info:** `userAgent`, `browser`, `operatingSystem`, `platform`, `language`, `timezone`, `screenResolution`, `colorDepth`, `timestamp`, `ipAddress`, `location` (latitude, longitude; solo si hay permiso de ubicación), `deviceId`, `deviceName`
    * **gov\_entity\_data:** datos de la entidad gubernamental del país (campos varían según el país)
  </Accordion>
</AccordionGroup>

### Errores

<AccordionGroup>
  <Accordion title="Proceso abandonado" icon="door-open">
    El usuario abandonó el proceso antes de completarlo.

    **Variable:** `incomplete`

    **Descripción:** Proceso abandonado
  </Accordion>

  <Accordion title="Biometría Rechazada" icon="ban">
    La verificación biométrica falló o fue rechazada.

    **Variable:** `reject`

    **Descripción:** Biometría Rechazada
  </Accordion>

  <Accordion title="Error en el proceso" icon="triangle-exclamation">
    Error durante la ejecución del proceso de biometría.

    **Variable:** `error`

    **Descripción:** Error en el proceso
  </Accordion>
</AccordionGroup>

## ¿Cómo personalizar la experiencia?

<Steps>
  <Step title="Abre el panel de Biometría">
    Haz clic en el botón **Configurar Webviews** del nodo Biometría o dirígete al panel lateral izquierdo de la plataforma, a la sección **Biometría**.
  </Step>

  <Step title="Conoce las secciones de Biometría">
    En la sección **Biometría** verás:

    * **Actividad:** muestra todas las biometrías realizadas en detalle, con el estado por etapa y el acceso al reporte biométrico.
    * **Configuración Webviews:** te permite crear agentes de biometría con diferente configuración, experiencia, colores y estilos, mensajes y pantallas, que podrás utilizar dentro de una misma compañía o workflow.
  </Step>

  <Step title="Configura tu Webview">
    En **Configuración Webviews** verás las pestañas de configuración del agente. Cada pestaña se explica a continuación.
  </Step>
</Steps>

<Info>
  Mientras configuras, la plataforma muestra una vista previa del teléfono. Puedes personalizar cómo se ve y qué dice el Webview, pero no cómo funciona la captura ni sus controles de seguridad. Es una restricción intencional para mantener el estándar de verificación.
</Info>

<AccordionGroup>
  <Accordion title="General" icon="sliders">
    Configura las reglas de rendimiento básicas del agente. Aquí se deben reflejar las principales reglas de negocio de tu cliente.

    **País de la validación**

    Define los documentos que deben ser aceptados y contra qué registro oficial se valida.

    **¿Qué incluye la biometría?**

    * **Prueba de vida, verificación de documento y comparación facial:** son la base del proceso y no se pueden desactivar.
    * **Habilitar revisión gubernamental:** valida los datos del documento contra una fuente oficial.
    * **Facematch con entidad gubernamental:** compara la selfie con la foto oficial de la fuente gubernamental. **Solo está disponible en Ecuador.**

    Conoce el detalle en [Validación gubernamental](/guides/integraciones/identidad/validacion-gubernamental).

    <Warning>
      Si necesitas desactivar la validación gubernamental, envía un correo a soporte o levanta un ticket de client request al equipo de Producto Biometría.
    </Warning>

    **¿Qué documentos permite?**

    * **Documento nacional de identidad.**
    * **Pasaporte del país de validación.** El pasaporte solo se puede capturar con la vista previa, así que activarlo fija esa experiencia en **Verificación de documento**.

    Con más de un tipo permitido, el usuario elige cuál presentar antes de la captura.

    **Tiempo de expiración**

    Define cuánto tiempo permanece activo el enlace del Webview antes de expirar. Por defecto son **60 minutos**.

    **Idioma**

    Es el idioma con el que abre la experiencia.
  </Accordion>

  <Accordion title="Branding" icon="palette">
    Adapta los colores y el estilo de la experiencia a tu marca. Se organiza en tres secciones: **Marca**, **Logo** e **Interfaz**. Los colores se configuran por separado en **modo claro** y **modo oscuro**.

    **Marca**

    * Colores de la marca: puntos del indicador de pasos completados.
    * Color de los botones principales, del enlace de términos y condiciones, de los spinners y de los pasos no completados.
    * Color de fondo y color de texto.
    * Color de los spinners en la pantalla final de verificación.
    * Estilo del stepper en el encabezado de todas las pantallas. Por defecto es circular.
    * Selector de idioma, para que el usuario pueda cambiar el idioma de la experiencia.

    **Logo**

    * **Logo de la empresa:** ingresa la URL de la imagen de tu logo. Puedes verlo en una vista previa antes de guardar.

    **Interfaz**

    * **Mostrar flecha en los botones principales:** activa o desactiva una flecha en los botones principales de la experiencia.
  </Accordion>

  <Accordion title="Pantalla Inicio" icon="house">
    Es la primera pantalla del proceso. Aquí el usuario acepta los términos y empieza la verificación.

    | Campo | Descripción |
    | - | - |
    | HTML de la pantalla | HTML propio de la pantalla. Si queda vacío, el Webview usa el de la pestaña **Predeterminada**. |
    | Texto del enlace legal | Por ejemplo, "Términos y condiciones". |
    | URL de términos y condiciones | URL pública que debe mencionar el uso, almacenamiento y tratamiento de datos personales y biométricos. |
  </Accordion>

  <Accordion title="Pantalla prueba de vida" icon="face-smile">
    Define las instrucciones para la selfie y el límite de intentos.

    **Máximo de intentos de la selfie**

    * Elige **1, 2 o 3** intentos. Por defecto son 2.
    * Es independiente del límite de intentos del documento.
    * Más intentos ayudan al usuario legítimo. Menos intentos limitan que alguien pruebe varias veces.

    **Diseño de la pantalla de instrucciones**

    * **Imagen y texto:** el Webview muestra su ilustración y debajo el texto que definas.
    * **Pantalla completa:** tu HTML reemplaza la ilustración y el texto. El encabezado con los pasos y el botón de continuar se mantienen.
  </Accordion>

  <Accordion title="Verificación de documento" icon="id-card">
    Define las instrucciones, la captura, los resultados y las reglas de seguridad del documento.

    | Configuración | Qué hace |
    | - | - |
    | Máximo de intentos | 1, 2 o 3 intentos. Por defecto son 2. |
    | Nivel de análisis del documento | Estándar, Avanzado o Personalizado. Revisa [Nivel de análisis del documento](/guides/integraciones/identidad/nivel-analisis-documento) antes de elegirlo. |
    | Habilitar revisión humana | Activa [HIL](/guides/integraciones/identidad/hil). Solo para cuentas Enterprise y con costo adicional. |
    | Habilitar validación de recaptura | Rechaza documentos fotografiados desde pantallas o impresiones. Para activarla, levanta un client request al equipo de Producto Biometría. |
    | Umbral de comparación facial | Porcentaje mínimo de coincidencia entre la selfie y la foto del documento. Por defecto es **70%**. Se ajusta en la sección **Seguridad**. |

    <Warning>
      **Revisa el nivel de análisis antes de publicar.** Es la configuración que más influye en la tasa de aprobación. Conoce cada nivel y la configuración recomendada por país en [Nivel de análisis del documento](/guides/integraciones/identidad/nivel-analisis-documento). Si requieres ayuda en definir la mejor configuración para tu documento, utiliza el [Onboarding con Jelou CLI](/guides/integraciones/identidad/onboarding-biometria).
    </Warning>

    <AccordionGroup>
      <Accordion title="Personalización de pantalla" icon="mobile-screen">
        Define las instrucciones, la captura y las pantallas de verificación del documento.

        **Pantalla de instrucciones del documento**

        * **Diseño de la pantalla:** elige **Imagen y texto** (el Webview muestra la ilustración de la pantalla y debajo tu bloque de texto) o **Pantalla completa** (tu HTML reemplaza la ilustración y el texto; el encabezado con los pasos y el botón de continuar se mantienen).
        * **HTML propio de la pantalla:** elige **De la empresa** para usar tu HTML o **Por defecto** para usar el del Webview. Si no defines HTML propio, el Webview usa el de la pestaña **Por defecto**.

        **Imagen de la pantalla de documento**

        Ingresa la URL de la imagen que se muestra en la pantalla de documento. Puedes verla en una vista previa.

        **Captura del documento**

        Define la experiencia que vive el usuario final al capturar el frente y el reverso de su documento. Elige una de estas opciones:

        | Opción | Qué ve el usuario |
        | - | - |
        | **Cuenta regresiva** | Después de capturar el frente, ve un contador de 5 segundos que le indica voltear el documento y tomar el reverso. |
        | **Vista previa** | Después de cada captura, ve la foto tomada y decide si repetirla o continuar. Al confirmar el frente, se activa un contador de 5 segundos que le avisa que debe voltear el documento. Al capturar el reverso, también ve la foto para confirmarla. Aplica al frente y al reverso. |

        <Note>
          El pasaporte solo se puede capturar con la opción **Vista previa**. Al permitir el pasaporte en la pestaña **General**, esa opción queda fija.
        </Note>

        **Pantalla verificación de información**

        Lista de pasos que el usuario ve mientras se analiza su documento. Puedes editar cada texto; si lo dejas vacío, se usa el texto por defecto.

        | Proceso | Descripción del proceso | Lo que ve el usuario por defecto |
        | - | - | - |
        | Título de la pantalla | Encabezado mientras corre el análisis. | Analizando tu documento |
        | Paso: lectura de datos | Extracción OCR de los datos del documento. | Obteniendo los datos de tu documento |
        | Paso: autenticidad | Detección de recaptura (foto de pantalla o impresión). Solo aparece con la detección de recaptura activa. | Verificando autenticidad del documento |
        | Paso: integridad | Análisis de manipulación de la imagen. | Verificando integridad del documento |
        | Paso: entidad gubernamental | Contraste con el registro civil. Solo aparece con la validación gubernamental activa. | Validando con la entidad gubernamental |
        | Paso: coincidencia facial | Comparación entre la selfie y la foto del documento. | Verificando coincidencia facial |

        **Pantalla éxito**

        Es lo que el usuario ve cuando el documento fue validado. El texto por defecto de cada campo es el que usa el Webview si lo dejas vacío. También puedes usar **HTML propio de la pantalla** (**De la empresa** o **Por defecto**).
      </Accordion>

      <Accordion title="Validación de recaptura" icon="camera-rotate">
        Una **recaptura** ocurre cuando el usuario fotografía una pantalla o una impresión del documento, en vez del documento físico. Esta validación es una capa extra de seguridad que protege tu operación frente a intentos de suplantación con fotos de pantallas.

        Ten en cuenta que la herramienta analiza fotos de pantallas, pero también puede marcar fotos con muchos brillos o reflejos, por ejemplo por luz directa o documentos plastificados. Estos casos pueden considerarse falsos positivos y afectar la tasa de aprobación.

        <Tip>
          Antes de activarla, evalúa las condiciones en que tus usuarios suelen tomar la foto. Si ya tienes revisión humana (HIL), esos casos pueden revisarse en lugar de rechazarse. Para activar la validación de recaptura, levanta un client request al equipo de Producto Biometría.
        </Tip>

        <Warning>
          Al activarla, el análisis es más riguroso: puede aumentar el tiempo total del proceso y disminuir la tasa de aprobación cuando los documentos presenten reflejos o destellos por luz interior.
        </Warning>
      </Accordion>

      <Accordion title="Umbral de comparación facial" icon="face-viewfinder">
        Un umbral alto prioriza la seguridad y rechaza más. Un umbral bajo prioriza la aprobación y deja pasar más. Es una decisión de riesgo de tu empresa; ajústalo según el nivel de riesgo que tu operación puede aceptar.
      </Accordion>

      <Accordion title="Textos por defecto: resultado aprobado y errores" icon="message-lines">
        Si dejas un campo vacío, se usa el texto por defecto. El mismo texto se reutiliza en la pantalla de límite de intentos.

        | Pantalla | Cuándo aparece | Texto por defecto |
        | - | - | - |
        | Resultado aprobado | El documento fue verificado. | **Documento validado.** Tu documento de identidad ha sido verificado correctamente. |
        | Lectura de datos fallida | El OCR no pudo leer el documento. | No logramos leer la información de tu documento. Evita reflejos o exceso de luz. |
        | Recaptura detectada | El documento parece una foto de una pantalla o una impresión. | No logramos leer la información de tu documento. Evita brillos, exceso de luz o fotografías de pantallas. |
        | Integridad comprometida | Se detectó manipulación en la imagen. | No pudimos verificar la integridad de tu documento. Asegúrate de que sea un documento original y no haya sido modificado, y vuelve a intentarlo. |
        | Entidad gubernamental | El registro civil no confirmó los datos. | No pudimos validar tu documento con la entidad gubernamental. Verifica que los datos de tu documento sean legibles e intenta nuevamente. |
        | Frente y reverso distintos | Las dos caras son de documentos diferentes. | Detectamos una inconsistencia al validar tu documento. Por favor, intenta nuevamente. |
        | Coincidencia facial fallida | El rostro de la selfie no coincide con el del documento. | No fue posible comparar tu rostro con la foto del documento. Evita reflejos, sombras o luces fuertes al tomar la foto. |
        | Error genérico | Respaldo de todos los anteriores y límite de intentos. | No pudimos validar tu documento después de varios intentos. Por favor, contacta con soporte. |
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Mensajes en WhatsApp" icon="comments">
    Define lo que escribe el agente durante la validación.

    * Los mensajes del agente durante la validación, por momento de la conversación.
    * El idioma de cada mensaje.
    * La invitación a validar: título, mensaje, nota al pie y texto del botón.
    * El mensaje de espera.

    Los campos vacíos usan el texto por defecto:

    | Mensaje | Texto por defecto |
    | - | - |
    | Título | Voy a validar tu identidad |
    | Mensaje | Será rápido y seguro. Tus datos están protegidos y los usaremos para confirmar que eres tú. Yo te guiaré en el paso a paso. |
    | Nota al pie | Pulsa el botón para comenzar |
    | Texto del botón | Iniciar validación |
    | Mensaje de espera | En caso no quieras continuar, escribe SALIR. |
  </Accordion>

  <Accordion title="Modo QA" icon="flask">
    Es una opción solo para **versiones de prueba internas**. Le muestra al usuario final (QA) un cuadro de rendimiento al capturar la imagen del documento y, al finalizar, el detalle del fallo.

    <Warning>
      No lo habilites en versiones que usarán tus clientes finales.
    </Warning>
  </Accordion>
</AccordionGroup>

<Info>
  Esta configuración se guarda por Webview. Puedes crear varias versiones y elegir cuál usa cada nodo Biometría de tus flujos.
</Info>

## Preguntas frecuentes

<AccordionGroup>
  <Accordion title="¿Qué documentos se necesitan durante el proceso biométrico?">
    Se requieren fotos del **documento de identidad por ambos lados**: frontal y reverso.
  </Accordion>

  <Accordion title="¿Necesito una cuenta de WhatsApp verificada?">
    No. Si tu cuenta no está verificada, la web se abre en el navegador del teléfono en lugar de abrirse dentro de WhatsApp.
  </Accordion>

  <Accordion title="¿Puedo personalizar colores e idioma de la experiencia?">
    Sí. Puedes ajustar los colores y el estilo del stepper en la pestaña **Branding**, y el idioma de los mensajes de WhatsApp. Los widgets de captura facial y de documento no son modificables.
  </Accordion>

  <Accordion title="¿Cuántos outputs tiene este agente?">
    Tiene **1 output de éxito** (Biometría Aprobada) y **3 outputs de error** (Proceso abandonado, Biometría Rechazada, Error en el proceso). Cada uno puedes dirigirlo a mensaje personalizado o Connect.
  </Accordion>

  <Accordion title="¿Qué pasa si estoy teniendo muchos documentos rechazados?">
    En la mayoría de los casos, la causa es un nivel de análisis documental muy riguroso para el país. Revisa la pestaña **Verificación de documento** y ajusta el nivel según la configuración recomendada por país en [Nivel de análisis del documento](/guides/integraciones/identidad/nivel-analisis-documento).
  </Accordion>

  <Accordion title="¿Si tapo parte del documento que contiene información relevante, igual aprueba la verificación de documento?">
    En la etapa de verificación de documento se identifica el tipo de documento (país, año de emisión) y se compara contra una plantilla. Si el documento hace match y no presenta rasgos de manipulación, se aprueba, extrayendo los datos por medio de OCR. Si el elemento que cubre el documento no oculta información relevante, este puede ser aprobado; pero si la validación gubernamental está activa y los datos no son correctos, la biometría será rechazada.
  </Accordion>
</AccordionGroup>

<Card title="Siguiente: Reportes" icon="arrow-right" href="/guides/integraciones/identidad/reportes-biometria">
  Consulta la actividad y el reporte biométrico de cada proceso.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.