Configuracion del widget

Referencia completa de todo lo configurable en el custom element <veridia-widget>.

Todos los atributos

Atributo	Requerido	Default	Descripcion
`publishable-key`	Si	-	Tu key `qv_pub_` o `qv_pub_test_`
`api-base`	Si	-	Endpoint de la API (`https://api.xxuxe.online` para produccion)
`user-ref`	No	-	Tu propio identificador de usuario (max 128 chars)
`country`	No	-	Codigo ISO 3166-1 alpha-2 (`PY`, `BR`, `MX`, etc.)
`document-type`	No	-	`dni`, `passport`, `drivers_license`, `national_id`, o `other`
`submitted-full-name`	No	-	Nombre completo para fuzzy matching (max 255 chars)
`require-doc-back`	No	`"false"`	Setea `"true"` si el documento necesita captura de reverso
`locale`	No	browser	Idioma de UI: `en`, `es`, `pt`
`accent-color`	No	`#2563EB`	Color hex para botones y estados activos

Detalle de atributos

`publishable-key` (requerido)

La key que identifica tu tenant. Dos prefijos:

qv_pub_test_* — environment de test (gratis, no cuenta para facturacion)
qv_pub_* — environment live (facturacion real)

Obtene la tuya del dashboard en API keys.

<veridia-widget publishable-key="qv_pub_test_FJJWXMA2RN2XPRDK6YJX4KTVD0XSQHW9">

`api-base` (requerido)

El endpoint de la API Veridia. Para produccion siempre:

<veridia-widget api-base="https://api.xxuxe.online">

`user-ref` (opcional pero recomendado)

Tu propio identificador para el usuario. Eco en eventos de webhook como userRef. Max 128 chars. Patron recomendado: tu primary key de DB.

<veridia-widget user-ref="customer-12345">

`country` (opcional pero recomendado)

Codigo ISO 3166-1 alpha-2. Mejora el accuracy del OCR sugiriendo que layout de documento esperar.

<veridia-widget country="PY">

Codigos LATAM comunes:

Codigo	Pais
`PY`	Paraguay
`BR`	Brasil
`MX`	Mexico
`AR`	Argentina
`CO`	Colombia
`CL`	Chile
`PE`	Peru
`UY`	Uruguay

`document-type` (opcional)

Sugerencia de que documento va a enviar el usuario. El VLM igual valida, pero esto mejora el prompting.

Valor	Descripcion
`dni`	Tarjeta de identidad nacional (DNI, CI, cedula)
`passport`	Pasaporte
`drivers_license`	Licencia de conducir
`national_id`	ID nacional generico
`other`	Cualquier otro documento de identidad

<veridia-widget document-type="dni">

`submitted-full-name` (opcional)

El nombre legal completo del usuario como lo tipeo en tu form. Usado por el backend para fuzzy matching contra el nombre OCRdo. Mejora el accuracy del veredicto cuando los nombres matchean.

<veridia-widget submitted-full-name="Juan Carlos Perez Gonzalez">

Si el resultado del OCR matchea (permitiendo typos y orden), boostea la confianza. Si no matchea para nada, se dispara un flag name_mismatch.

`require-doc-back` (opcional)

Setealo en "true" si tu tipo de documento requiere foto del reverso. Default "false".

<veridia-widget require-doc-back="true">

Cuando es "true", el widget agrega un tercer paso de captura entre el frente del documento y la selfie.

Cuando lo necesitas: la mayoria de los DNIs/CIs latinoamericanos tienen info importante (direccion, MRZ) en el reverso. RG brasilenia, INE mexicana, y similares siempre necesitan ambos lados.

`locale` (opcional)

Idioma de UI. Default es el idioma del browser, fallback a ingles.

Valor	Idioma
`en`	Ingles
`es`	Espanol
`pt`	Portugues (Brasil)

<veridia-widget locale="es">

`accent-color` (opcional)

Color hex para botones primarios, estados activos e indicadores de progreso. Default #2563EB (azul).

<veridia-widget accent-color="#7C3AED">  <!-- violeta -->
<veridia-widget accent-color="#10B981">  <!-- verde -->
<veridia-widget accent-color="#F59E0B">  <!-- ambar -->

Quedate con colores que tengan contraste WCAG AA contra blanco. Evita pasteles — fallan en accessibility checks.

Eventos

El widget emite dos CustomEvents en el elemento host.

`veridia:complete`

Disparado cuando el usuario termina las capturas y la API acepta el envio. El veredicto NO esta en este evento — todavia tenes que obtenerlo de la API o esperar el webhook.

widget.addEventListener('veridia:complete', (e) => {
  console.log(e.detail);
  // {
  //   verificationId: "vf_AG07CDWRRFQV4T05ZXG2",
  //   userRef: "customer-12345",
  //   status: "queued"
  // }
});

El e.detail contiene:

Campo	Tipo	Descripcion
`verificationId`	string	El ID para obtener el veredicto
`userRef`	string \| null	El `user-ref` que pasaste
`status`	string	Status inicial — usualmente `"queued"`

`veridia:error`

Disparado cuando algo sale mal client-side de lo que el usuario no puede recuperarse (falla de auth, red caida, etc.).

widget.addEventListener('veridia:error', (e) => {
  console.error(e.detail);
  // {
  //   code: "errorInvalidKey",
  //   message: "API key invalida o revocada",
  //   detail: { ... }
  // }
});

El e.detail contiene:

Campo	Tipo	Descripcion
`code`	string	Codigo de error machine-readable
`message`	string	Resumen human-readable
`detail`	object	Contexto extra opcional

Codigos de error comunes:

Codigo	Significado
`errorInvalidKey`	Publishable key mala/revocada
`errorRateLimited`	Demasiadas requests
`errorInsufficientCredits`	El tenant tiene 0 creditos
`errorBlurry`	Calidad de captura debajo del threshold (auto-reintentado)
`errorNoFace`	La selfie no tiene cara detectable (auto-reintentado)
`errorUpload`	El upload R2 fallo (auto-reintentado)
`errorNetwork`	Falla de red generica

El widget maneja errorBlurry, errorNoFace, y errorUpload automaticamente pidiendole al usuario que reintente. Los otros codigos llegan a tu handler.

Actualizando atributos en runtime

Podes cambiar atributos via JavaScript. El widget se actualiza reactivamente:

const widget = document.querySelector('veridia-widget');

// Cambiar locale dinamicamente
widget.setAttribute('locale', 'pt');

// Cambiar color de accent
widget.setAttribute('accent-color', '#10B981');

// Cambiar pais (debe pasar antes que el usuario empiece a capturar)
widget.setAttribute('country', 'BR');

Limitacion: cambiar publishable-key despues que el widget fue usado una vez resetea el estado interno. No hagas esto mid-flow.

Sizing

El widget es responsivo por defecto. Trata de llenar el ancho de su container, con altura minima de 380px.

veridia-widget {
  display: block;
  width: 100%;
  max-width: 600px;
  min-height: 480px;
  margin: 0 auto;
}

El layout interno se adapta a mobile (debajo de 480px) automaticamente.

Estilos

El widget usa Shadow DOM para aislamiento de estilos. El CSS de tu pagina no afecta los internos del widget, y el CSS del widget no se filtra hacia afuera.

Lo que podes customizar:

Atributo accent-color (color primario)
Tamano del elemento container (width, height, margin)
Contenido afuera (heading de tu pagina, instrucciones, etc.)

Lo que no podes customizar sin forkear:

Tipografia interna
Espaciado interno
Diseno de overlay de captura

Si necesitas customizacion mas profunda, contacta soporte — ofrecemos un tier white-label con temas custom.

Multiples widgets en la misma pagina

Podes tener multiples instancias de widget en una pagina (ej. uno para usuario primario, uno para garante). Cada uno opera independientemente:

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

<script>
  document.getElementById('primary-user').addEventListener('veridia:complete', (e) => {
    // Manejar usuario primario
  });
  document.getElementById('guarantor').addEventListener('veridia:complete', (e) => {
    // Manejar garante
  });
</script>

Cada instancia carga face-api.js una vez globalmente — sin doble penalizacion de carga.

Notas de performance

Primera carga: ~6 MB face-api.js + ~150 KB widget = ~6.2 MB. La mayoria de usuarios en 4G lo cargan en 2-3 segundos.
Cargas subsecuentes: cacheado por el browser; casi instantaneo.
Model files: ~14 MB lazy-loaded la primera vez que el usuario empieza una captura. Cacheado despues.
Bandwidth total por verificacion: ~20 MB primera vez, ~150 KB en uso repetido.

Para usuarios en conexiones lentas, considera un UI placeholder que muestre mientras los scripts cargan:

<div id="kyc-placeholder">
  Cargando widget de verificacion...
</div>
<veridia-widget id="kyc" hidden ...></veridia-widget>

<script>
  customElements.whenDefined('veridia-widget').then(() => {
    document.getElementById('kyc-placeholder').remove();
    document.getElementById('kyc').hidden = false;
  });
</script>

Que sigue

Instalacion del widget — setup por framework
Quickstart — recorrido completo de integracion
Referencia API — API server-side para obtener veredictos

Todos los atributos​

Detalle de atributos​

publishable-key (requerido)​

api-base (requerido)​

user-ref (opcional pero recomendado)​

country (opcional pero recomendado)​

document-type (opcional)​

submitted-full-name (opcional)​

require-doc-back (opcional)​

locale (opcional)​

accent-color (opcional)​

Eventos​

veridia:complete​

veridia:error​

Actualizando atributos en runtime​

Sizing​

Estilos​

Multiples widgets en la misma pagina​

Notas de performance​

Que sigue​