Configuración del widget
Referencia completa de todo lo que podés configurar en el custom element <veridia-widget>.
Todos los atributos
Se observan diez atributos. Solo uno es obligatorio.
| Atributo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|
publishable-key | Sí | — | Tu clave qv_pub_* o qv_pubt_* |
api-base | No | https://api.xxuxe.online | Endpoint de la API |
user-ref | No | — | Tu propio identificador de usuario (máx. 128 caracteres) |
country | No | — | Código de país ISO 3166-1 alfa-2 (PY, BR, MX, …) |
document-type | No | — | dni, passport, drivers_license, national_id, other |
submitted-full-name | No | — | Nombre completo del usuario para el cotejo difuso (máx. 255 caracteres) |
require-doc-back | No | activado, salvo para pasaportes | Si se captura el dorso del documento |
locale | No | idioma del navegador, luego en | Idioma de la interfaz: en, es, pt |
accent-color | No | #0f172a | Cualquier color CSS válido |
active-liveness | No | desactivado | Activar el reto de prueba de vida (liveness) activa RBS-2 |
Detalle de cada atributo
publishable-key (obligatorio)
El único atributo obligatorio. Identifica a tu tenant. Dos prefijos:
qv_pubt_*— entorno de testqv_pub_*— entorno de producción
Ojo que el prefijo de test es qv_pubt_, no qv_pub_test_.
<veridia-widget publishable-key="qv_pubt_FJJWXMA2RN2XPRDK6YJX4KTVD0XSQHW9">
Conseguí la tuya en el panel, en API keys.
Una clave publicable puede iniciar y enviar verificaciones. No puede leer veredictos: GET /v1/verify/{id} le devuelve 401 secret_key_required. Esa restricción es justamente la razón por la que es seguro poner esta clave en el código fuente de tu página. Nunca pongas una clave qv_sec_* / qv_sect_* en un navegador.
Si este atributo falta cuando el usuario presiona Comenzar, el widget emite veridia:error con el código invalid_api_key.
api-base (opcional)
El endpoint de la API de Veridia. Por defecto es https://api.xxuxe.online, así que en producción podés omitirlo por completo.
<veridia-widget api-base="https://api.xxuxe.online">
Definilo solo si te dieron un endpoint distinto.
user-ref (opcional pero recomendado)
Tu propio identificador del usuario. Máx. 128 caracteres. Típicamente la clave primaria de tu base de datos.
<veridia-widget user-ref="customer-12345">
Se devuelve en el payload del webhook, bajo userRef.
No se devuelve en el evento veridia:complete, y no lo devuelve GET /v1/verify/{id}. Si tu integración lee el veredicto por polling en lugar de por webhook, user-ref nunca te va a volver: guardá vos mismo el mapeo verificationId → usuario cuando se dispare veridia:complete. Ver Eventos.
country (opcional pero recomendado)
Código de país ISO 3166-1 alfa-2. Sugiere qué diseño de documento esperar, lo que mejora la precisión del OCR. El widget lo pasa a mayúsculas por vos, así que py funciona igual que PY.
<veridia-widget country="PY">
| Código | País |
|---|---|
PY | Paraguay |
BR | Brasil |
MX | México |
AR | Argentina |
CO | Colombia |
CL | Chile |
PE | Perú |
UY | Uruguay |
document-type (opcional)
Indicación de qué documento va a presentar el usuario.
| Valor | Descripción |
|---|---|
dni | Documento nacional de identidad (DNI, CI, cédula) |
passport | Pasaporte |
drivers_license | Licencia de conducir |
national_id | Identificación nacional genérica |
other | Cualquier otro documento de identidad |
Cualquier otro valor se ignora: el atributo se valida, no se confía en él.
<veridia-widget document-type="dni">
Esto también decide el valor por defecto de require-doc-back, más abajo.
submitted-full-name (opcional)
El nombre legal completo del usuario tal como lo escribió en tu formulario. Máx. 255 caracteres. El backend lo coteja de forma difusa contra el nombre extraído por OCR y reporta el resultado como el score name_match.
<veridia-widget submitted-full-name="Juan Carlos Perez Gonzalez">
require-doc-back (opcional)
Si el widget pide una foto del dorso del documento.
El valor por defecto es activado para todos los tipos de documento excepto passport. Si no definís ni require-doc-back ni document-type, el widget pide el dorso: tres pasos de captura, no dos. Los pasaportes no tienen dorso, así que document-type="passport" elimina el paso por sí solo.
Desactivarlo requiere exactamente la cadena "false" o "0":
<!-- Desactivado: dos pasos de captura. -->
<veridia-widget document-type="dni" require-doc-back="false">
<!-- ACTIVADO. "no" no es "false", y un valor vacío tampoco. -->
<veridia-widget document-type="dni" require-doc-back="no">
<veridia-widget document-type="dni" require-doc-back="">
Todo lo que no sea "false" o "0" resuelve a verdadero. Esto es lo opuesto a la convención habitual de atributos booleanos de HTML, donde la sola presencia significa verdadero y el valor se ignora: acá lo que cuenta es el valor.
Cuándo necesitás el dorso: la mayoría de los DNI/CI latinoamericanos llevan el domicilio y los datos MRZ en el reverso. El RG brasileño, el INE mexicano y similares necesitan ambos lados.
locale (opcional)
Idioma de la interfaz: en, es o pt. Por defecto usa navigator.language, con fallback a inglés para cualquier cosa que no reconozca.
<veridia-widget locale="es">
accent-color (opcional)
Color principal de botones, enlaces, contornos de foco e indicadores de progreso. Por defecto #0f172a (slate-900, casi negro), no azul.
Acepta cualquier color CSS válido, no solo hexadecimal. Ver Personalización.
<veridia-widget accent-color="#7C3AED">
active-liveness (opcional)
Activa el reto de prueba de vida (liveness) activa RBS-2: un reto de pose de cabeza y destello reactivo, emitido por el servidor, que corre después de la selfie. Desactivado por defecto.
<veridia-widget active-liveness="true">
Igual que con require-doc-back, los únicos valores que significan desactivado son "false" y "0"; cualquier otro valor lo activa. La presencia del atributo sin valor lo deja activado.
Dos cosas para tener en cuenta:
- El reto agrega un paso al flujo del usuario y lleva tiempo completarlo.
- Realiza muchas más subidas que el flujo simple (unas 20 por verificación). Eso importa frente al límite de tasa por IP de 100 requests / 60 s: varios usuarios móviles detrás de la misma dirección CGNAT pueden agotarlo en plena captura. Ver Límites de tasa.
Configuración programática
En lugar de atributos, podés definir el objeto de configuración completo desde JavaScript:
const widget = document.querySelector('veridia-widget');
widget.config = {
publishableKey: 'qv_pubt_YOUR_KEY',
userRef: 'customer-12345',
country: 'PY',
documentType: 'dni',
requireDocBack: false,
locale: 'es',
accentColor: '#7C3AED',
activeLiveness: true,
};
Los nombres de propiedad van en camelCase, reflejando los atributos en kebab-case. Asignar config re-renderiza inmediatamente.
Es la mejor opción cuando tus valores vienen del estado de la aplicación, y la única opción para valores que preferís no dejar en el DOM.
Cambiar atributos en tiempo de ejecución
Cambiar un atributo observado vuelve a leer todos los atributos y re-renderiza:
widget.setAttribute('locale', 'pt');
widget.setAttribute('accent-color', '#10B981');
config con cambios de atributosLos atributos son la autoridad. Tocar cualquier atributo observado reconstruye la configuración únicamente a partir de los atributos: todo lo que hayas definido con el setter config se descarta en ese instante, incluida publishableKey.
La falla concreta: configurás el widget con widget.config = {...}, después cambiás el idioma con setAttribute('locale', 'pt'). La clave ahora está vacía, el usuario presiona Comenzar, y el flujo muere con invalid_api_key y una pantalla de "mal configurado" que te manda a auditar un panel donde no hay nada mal.
Elegí un mecanismo. Si configurás de forma programática, cambiá el idioma asignando un nuevo objeto config, no definiendo un atributo.
Los cambios de configuración no reinician la máquina de estados. Cambiá country o document-type antes de que el usuario empiece a capturar: los cambios a mitad de flujo no alteran retroactivamente los pasos ya realizados.
Varios widgets en la misma página
Pueden coexistir varias instancias (solicitante y garante, por ejemplo). Cada una mantiene su propia configuración, cámara y estado.
<veridia-widget id="primary-user" publishable-key="…" user-ref="user-123"></veridia-widget>
<veridia-widget id="guarantor" publishable-key="…" user-ref="guarantor-456"></veridia-widget>
face-api.js se carga una sola vez de forma global por la etiqueta de script: no hay penalización de carga por instancia. Hay un ejemplo completo en Ejemplos.
Tamaño del payload
Medido sobre el build actual:
| Recurso | Tamaño | Cuándo |
|---|---|---|
face-api.js | ~1,33 MB | Al cargar la página |
veridia-widget.min.js | ~45 KB | Al cargar la página |
Modelo de detección de rostro (tiny_face_detector) | ~196 KB | De forma diferida, en la primera captura |
Unos 1,6 MB en total con caché fría, y después queda cacheado por el navegador. Se carga un solo modelo, no el set completo de face-api.
Si leíste una cifra como 20 MB en una versión anterior de esta página, estaba equivocada por más de diez veces: vale la pena revisarlo si ese número descartó al widget para una audiencia con datos limitados.
Estilos y tamaño
El widget se renderiza en un Shadow DOM, así que el CSS de tu página no puede alcanzar su interior y su CSS no se filtra afuera. La superficie de personalización es accent-color, locale, la caja del elemento anfitrión, y el subclaseo.
La tarjeta interna está limitada a max-width: 440px y no define ninguna altura mínima de contenedor. Todos los detalles, incluido el subclaseo, están en Personalización.
Eventos y códigos de error
El widget emite dos eventos, veridia:complete y veridia:error. La lista completa de códigos de error vive en Eventos.
Si estás buscando códigos como errorInvalidKey o errorBlurry, nunca fueron códigos de error: son nombres internos de cadenas de traducción que una versión anterior de esta página publicó por error. Los códigos reales son camera_denied, camera_unavailable, upload_failed, api_unreachable, invalid_api_key, insufficient_credits, rate_limited, user_cancelled e internal_error.
Qué sigue
- Eventos — la forma de los eventos y la tabla completa de códigos de error.
- Personalización — color de acento, idioma, tamaño, subclaseo.
- Instalación — configuración específica por framework.
- Referencia de la API — la API del lado del servidor que devuelve veredictos.