Entrega del Widget
El widget es una aplicación web alojada que guía a su cliente a través de la captura del documento y la selfie. Usted no construye el manejo de cámara, la guía de encuadre ni el acompañamiento de reintentos — usted entrega una URL.
La URL
POST /v1/sessions devuelve:
{ "widget_url": "https://{FQDN}/verify/8Kd2mQ…" }
El segmento final es un código de arranque de un solo uso, no un identificador de sesión. Cuando la página carga, el navegador lo intercambia por un token de página de corta duración; el código en sí no otorga nada más allá de iniciar esa única verificación.
| Propiedad | Comportamiento |
|---|---|
| Vigencia | 48 horas desde la creación de la sesión |
| Alcance | Una sesión. No expone datos del tenant y no puede usarse para leer un resultado |
| Enlace vencido | El cliente ve un mensaje de enlace vencido — cree una nueva sesión |
| Sesión ya completada | Reabrir una verificación terminada muestra un mensaje de finalización en lugar de empezar de nuevo |
Como el enlace tiene tiempo limitado, genérelo cuando esté listo para enviarlo — no por adelantado, en lote.
Tres Formas de Entregarlo
| Método | Cómo | Ideal para |
|---|---|---|
| Redirección | Envíe el navegador del cliente a widget_url, y use la entrega por redirección para traerlo de vuelta | Flujos de onboarding web |
| Webview nativo | Abra widget_url en un webview del sistema (WKWebView, WebView de Android) con permiso de cámara concedido | Aplicaciones móviles que mantienen al cliente dentro de la app |
| Enlace externo | Envíe la URL por SMS, WhatsApp o correo electrónico | Flujos de escritorio o asistidos por un agente donde el teléfono del cliente tiene la mejor cámara |
No hay SDK de JavaScript, API de iframe ni flujo de eventos postMessage. La finalización se señala del lado del servidor — mediante el webhook firmado o la redirección firmada — que es también lo que la hace confiable: el desenlace sobre el que actúa su backend nunca pasa sin firmar por el navegador del cliente.
Requisitos de Cámara
El acceso a la cámara requiere un contexto seguro. En la práctica:
- Sirva o abra el widget por HTTPS.
http://localhostyhttp://127.0.0.1también califican, para desarrollo local. - En un webview nativo, conceda el permiso de cámara antes de cargar la URL — el aviso del sistema operativo dentro de un webview es fácil de pasar por alto para los clientes.
- La captura es solo con cámara por defecto. Un selector de archivos aparece únicamente si la carga de archivos está habilitada para su tenant, de modo que un cliente no puede subir una foto almacenada de un documento a menos que usted nos haya pedido permitirlo.
Las imágenes tienen un tope de 10 MB por captura, dentro del cual la propia codificación del widget se mantiene con holgura.
Qué Ve el Cliente
- Tipo de documento — pasaporte, licencia de conducir o cédula de identidad. Se omite cuando usted establece
prefill.document_type, y se limita a los tipos habilitados para su tenant. - Captura del documento — una máscara con la forma del documento (página de foto y zona de lectura mecánica del pasaporte, contorno de tarjeta ID-1) con retroalimentación en vivo de encuadre, reflejos y desenfoque. Los documentos de dos caras solicitan el reverso.
- Confirmación — los campos extraídos se muestran para que el cliente pueda detectar una lectura errónea antes de continuar.
- Selfie — un óvalo facial con guía de captura.
- Resultado — aprobado, rechazado o un mensaje de "en revisión". En modo redirección el cliente es devuelto a su URL en su lugar.
Reintentos de Captura
Una captura que no puede verificarse — demasiado borrosa para leerse, una foto de una pantalla, un rostro que no coincide — devuelve al cliente al paso correspondiente con retroalimentación específica en lugar de hacer fallar la sesión de plano.
| Comportamiento | Detalle |
|---|---|
| Límite de intentos | El predeterminado de su tenant (3 salvo configuración distinta), sobrescribible por sesión con max_capture_attempts |
| En cada fallo | El cliente ve retroalimentación dirigida al problema específico y reintenta |
| Al agotarse | La sesión es rechazada, y usted recibe ese resultado como cualquier otro, con una comprobación capture_attempts que indica el límite alcanzado |
Eleve el límite para un flujo de consumo indulgente; redúzcalo donde las capturas fallidas repetidas sean en sí mismas una señal de fraude.
Marca y Localización
Ambas se configuran por tenant durante el onboarding — vea Configuración del Tenant.
La marca aplica su logo, nombre de empresa y colores primario, de fondo y de texto al marco del widget, de modo que el flujo se perciba como parte de su producto. El pie de página "Powered by Inyo 360" siempre se muestra y de manera intencional no es configurable.
El idioma proviene del campo language de la sesión, con respaldo en su valor predeterminado configurado. Inglés, portugués y español vienen completos; cualquier código xx o xx-XX es aceptado, y cualquier cadena sin traducción recurre al inglés de forma individual en lugar de descartar el idioma completo. Cada cadena que el widget muestra se sirve desde el almacén de textos de Inyo, así que la redacción — incluyendo la retroalimentación de reintentos y las pantallas de resultado — puede ajustarse para su tenant sin un despliegue de su parte.
Comprobación de Presencia Humana
El widget puede presentar un breve desafío de Cloudflare al iniciar, para evitar que el tráfico automatizado consuma verificaciones. Es invisible o casi invisible para los clientes reales y no requiere nada de su integración.
Seguimiento del Progreso
No necesita vigilar el progreso del cliente — el resultado se le envía por push — pero GET /v1/sessions/{session_id} expone un campo step (document_front, document_back, selfie, done) por si quiere mostrar un estado en curso en su propia UI o medir el abandono entre pasos.
Próximos Pasos
- Recepción de Resultados — verificación de firmas para ambos modos de entrega
- Configuración del Tenant — marca, tipos de documento permitidos, comportamiento de captura
- Verificación Servidor a Servidor — la alternativa cuando usted es dueño de la UI de captura