Configuracao do widget

Referencia completa de tudo o que e configuravel no custom element <veridia-widget>.

Todos os atributos

Atributo	Obrigatorio	Default	Descricao
`publishable-key`	Sim	-	Sua key `qv_pub_` ou `qv_pub_test_`
`api-base`	Sim	-	Endpoint da API (`https://api.xxuxe.online` para producao)
`user-ref`	Nao	-	Seu proprio identificador de usuario (max 128 chars)
`country`	Nao	-	Codigo ISO 3166-1 alpha-2 (`PY`, `BR`, `MX`, etc.)
`document-type`	Nao	-	`dni`, `passport`, `drivers_license`, `national_id`, ou `other`
`submitted-full-name`	Nao	-	Nome completo para fuzzy matching (max 255 chars)
`require-doc-back`	Nao	`"false"`	Defina `"true"` se o documento precisar de captura do verso
`locale`	Nao	browser	Idioma da UI: `en`, `es`, `pt`
`accent-color`	Nao	`#2563EB`	Cor hex para botoes e estados ativos

Detalhe dos atributos

`publishable-key` (obrigatorio)

A key que identifica seu tenant. Dois prefixos:

qv_pub_test_* — environment de teste (gratis, nao conta para faturamento)
qv_pub_* — environment live (faturamento real)

Obtenha a sua do dashboard em API keys.

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

`api-base` (obrigatorio)

O endpoint da API Veridia. Para producao sempre:

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

`user-ref` (opcional mas recomendado)

Seu proprio identificador para o usuario. Ecoado em eventos de webhook como userRef. Max 128 chars. Padrao recomendado: sua primary key do DB.

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

`country` (opcional mas recomendado)

Codigo ISO 3166-1 alpha-2. Melhora o accuracy do OCR sugerindo qual layout de documento esperar.

<veridia-widget country="BR">

Codigos LATAM comuns:

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

`document-type` (opcional)

Sugestao de qual documento o usuario vai enviar. O VLM ainda valida, mas isso melhora o prompting.

Valor	Descricao
`dni`	Cartao de identidade nacional (DNI, CI, cedula)
`passport`	Passaporte
`drivers_license`	Carteira de motorista
`national_id`	ID nacional generico
`other`	Qualquer outro documento de identidade

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

`submitted-full-name` (opcional)

O nome legal completo do usuario como digitado no seu form. Usado pelo backend para fuzzy matching contra o nome OCRdo. Melhora o accuracy do veredicto quando os nomes batem.

<veridia-widget submitted-full-name="Joao Carlos Silva Souza">

Se o resultado do OCR bate (permitindo typos e ordenacao), boosta a confianca. Se nao bate, dispara um flag name_mismatch.

`require-doc-back` (opcional)

Defina "true" se seu tipo de documento exigir foto do verso. Default "false".

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

Quando "true", o widget adiciona um terceiro passo de captura entre a frente do documento e a selfie.

Quando voce precisa: a maioria dos DNIs/CIs latinoamericanos tem info importante (endereco, MRZ) no verso. RG brasileiro, INE mexicana, e similares sempre precisam ambos lados.

`locale` (opcional)

Idioma da UI. Default e o idioma do browser, fallback ingles.

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

<veridia-widget locale="pt">

`accent-color` (opcional)

Cor hex para botoes primarios, estados ativos e indicadores de progresso. Default #2563EB (azul).

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

Use cores com contraste WCAG AA contra branco. Evite pasteis — falham checks de acessibilidade.

Eventos

O widget emite dois CustomEvents no elemento host.

`veridia:complete`

Disparado quando o usuario termina as capturas e a API aceita o envio. O veredicto NAO esta neste evento — voce ainda precisa obte-lo da API ou esperar o webhook.

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

O e.detail contem:

Campo	Tipo	Descricao
`verificationId`	string	O ID para obter o veredicto
`userRef`	string \| null	O `user-ref` que voce passou
`status`	string	Status inicial — geralmente `"queued"`

`veridia:error`

Disparado quando algo da errado client-side de que o usuario nao pode se recuperar (falha de auth, rede caida, etc.).

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

O e.detail contem:

Campo	Tipo	Descricao
`code`	string	Codigo de erro machine-readable
`message`	string	Resumo human-readable
`detail`	object	Contexto extra opcional

Codigos de erro comuns:

Codigo	Significado
`errorInvalidKey`	Publishable key ruim/revogada
`errorRateLimited`	Muitas requests
`errorInsufficientCredits`	O tenant tem 0 creditos
`errorBlurry`	Qualidade de captura abaixo do threshold (auto-retried)
`errorNoFace`	A selfie nao tem rosto detectavel (auto-retried)
`errorUpload`	O upload R2 falhou (auto-retried)
`errorNetwork`	Falha de rede generica

O widget gerencia errorBlurry, errorNoFace, e errorUpload automaticamente pedindo ao usuario para tentar de novo. Os outros codigos chegam ao seu handler.

Atualizando atributos em runtime

Voce pode mudar atributos via JavaScript. O widget se atualiza reativamente:

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

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

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

// Mudar pais (deve acontecer antes do usuario comecar a capturar)
widget.setAttribute('country', 'BR');

Limitacao: mudar publishable-key apos o widget ter sido usado uma vez reseta o estado interno. Nao faca isso mid-flow.

Sizing

O widget e responsivo por padrao. Tenta preencher a largura do seu container, com altura minima de 380px.

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

O layout interno se adapta a mobile (abaixo de 480px) automaticamente.

Estilos

O widget usa Shadow DOM para isolamento de estilos. O CSS da sua pagina nao afeta os internos do widget, e o CSS do widget nao vaza para fora.

O que voce pode customizar:

Atributo accent-color (cor primaria)
Tamanho do elemento container (width, height, margin)
Conteudo de fora (heading da sua pagina, instrucoes, etc.)

O que voce nao pode customizar sem forkar:

Tipografia interna
Espacamento interno
Design de overlay de captura

Se voce precisa de customizacao mais profunda, contate o suporte — oferecemos um tier white-label com temas custom.

Multiplos widgets na mesma pagina

Voce pode ter multiplas instancias de widget em uma pagina (ex: um para usuario primario, um para fiador). Cada um opera independentemente:

<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) => {
    // Gerenciar usuario primario
  });
  document.getElementById('guarantor').addEventListener('veridia:complete', (e) => {
    // Gerenciar fiador
  });
</script>

Cada instancia carrega face-api.js uma vez globalmente — sem dupla penalizacao de carga.

Notas de performance

Primeira carga: ~6 MB face-api.js + ~150 KB widget = ~6.2 MB. A maioria dos usuarios em 4G carrega em 2-3 segundos.
Cargas subsequentes: cacheado pelo browser; quase instantaneo.
Arquivos de modelo: ~14 MB lazy-loaded a primeira vez que o usuario inicia uma captura. Cacheado depois.
Bandwidth total por verificacao: ~20 MB primeira vez, ~150 KB em uso repetido.

Para usuarios em conexoes lentas, considere uma UI placeholder que mostra enquanto os scripts carregam:

<div id="kyc-placeholder">
  Carregando widget de verificacao...
</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>

Proximos passos

Instalacao do widget — setup por framework
Quickstart — caminho completo de integracao
Referencia API — API server-side para obter veredictos

Todos os atributos​

Detalhe dos atributos​

publishable-key (obrigatorio)​

api-base (obrigatorio)​

user-ref (opcional mas recomendado)​

country (opcional mas recomendado)​

document-type (opcional)​

submitted-full-name (opcional)​

require-doc-back (opcional)​

locale (opcional)​

accent-color (opcional)​

Eventos​

veridia:complete​

veridia:error​

Atualizando atributos em runtime​

Sizing​

Estilos​

Multiplos widgets na mesma pagina​

Notas de performance​

Proximos passos​