Configuração do widget

Referência completa de tudo o que você pode configurar no custom element <veridia-widget>.

Todos os atributos

Dez atributos são observados. Apenas um é obrigatório.

Atributo	Obrigatório	Default	Descrição
publishable-key	Sim	—	Sua chave qv_pub_* ou qv_pubt_*
api-base	Não	https://api.xxuxe.online	Endpoint da API
user-ref	Não	—	Seu próprio identificador de usuário (máx. 128 chars)
country	Não	—	Código de país ISO 3166-1 alpha-2 (PY, BR, MX, …)
document-type	Não	—	dni, passport, drivers_license, national_id, other
submitted-full-name	Não	—	Nome completo do usuário para fuzzy matching (máx. 255 chars)
require-doc-back	Não	ligado, exceto para passaportes	Se deve capturar o verso do documento
locale	Não	locale do navegador, depois en	Idioma da UI: en, es, pt
accent-color	Não	#0f172a	Qualquer cor CSS válida
active-liveness	Não	desligado	Opt-in do desafio de prova de vida ativa RBS-2

Detalhe dos atributos

publishable-key (obrigatório)

O único atributo obrigatório. Ele identifica seu tenant. Dois prefixos:

• qv_pubt_* — ambiente de teste
• qv_pub_* — ambiente live

Note que o prefixo de teste é qv_pubt_, não qv_pub_test_.

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

Obtenha a sua no dashboard, em API keys.

Uma chave publicável pode iniciar e enviar verificações. Ela não pode ler vereditos — GET /v1/verify/{id} retorna 401 secret_key_required para ela. Essa restrição é toda a razão pela qual é seguro colocar essa chave no código-fonte da sua página. Nunca coloque uma chave qv_sec_* / qv_sect_* em um navegador.

Se este atributo estiver ausente quando o usuário apertar iniciar, o widget emite veridia:error com o código invalid_api_key.

api-base (opcional)

O endpoint da API da Veridia. O default é https://api.xxuxe.online, então em produção você pode omiti-lo por completo.

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

Só defina se você recebeu um endpoint diferente.

user-ref (opcional, mas recomendado)

Seu próprio identificador para o usuário. Máx. 128 chars. Normalmente a chave primária do seu banco de dados.

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

Ele é devolvido no payload do webhook, sob userRef.

Ele não é retornado no evento veridia:complete, e não é retornado por GET /v1/verify/{id}. Se sua integração lê o veredito por polling em vez de webhook, user-ref nunca voltará para você — guarde você mesmo o mapeamento verificationId → usuário quando veridia:complete disparar. Veja Eventos.

country (opcional, mas recomendado)

Código de país ISO 3166-1 alpha-2. Indica qual layout de documento esperar, melhorando a precisão do OCR. O widget converte para maiúsculas por você, então py funciona igual a PY.

<veridia-widget country="PY">

Código	País
PY	Paraguai
BR	Brasil
MX	México
AR	Argentina
CO	Colômbia
CL	Chile
PE	Peru
UY	Uruguai

document-type (opcional)

Indicação de qual documento o usuário vai enviar.

Valor	Descrição
dni	Documento nacional de identidade (DNI, CI, cédula)
passport	Passaporte
drivers_license	Carteira de motorista
national_id	Identidade nacional genérica
other	Qualquer outro documento de identidade

Qualquer outro valor é ignorado — o atributo é validado, não confiado.

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

Isso também decide o default de require-doc-back, abaixo.

submitted-full-name (opcional)

O nome legal completo do usuário, como ele digitou no seu formulário. Máx. 255 chars. O backend faz fuzzy match dele contra o nome extraído por OCR e reporta o resultado como o score name_match.

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

require-doc-back (opcional)

Se o widget pede ou não uma foto do verso do documento.

O default é ligado para todo tipo de documento, exceto passport. Se você não definir nem require-doc-back nem document-type, o widget pede o verso — três etapas de captura, não duas. Passaportes não têm verso, então document-type="passport" remove a etapa por si só.

Desligar exige exatamente a string "false" ou "0":

<!-- Desligado: duas etapas de captura. -->
<veridia-widget document-type="dni" require-doc-back="false">

<!-- LIGADO. "no" não é "false", e um valor vazio também não. -->
<veridia-widget document-type="dni" require-doc-back="no">
<veridia-widget document-type="dni" require-doc-back="">

Qualquer coisa que não seja "false" ou "0" resolve para verdadeiro. Isso é o oposto da convenção usual de atributos booleanos em HTML, onde a mera presença significa verdadeiro e o valor é ignorado — aqui o valor é o que conta.

Quando você precisa do verso: a maioria dos DNIs/CIs latino-americanos traz endereço e dados de MRZ no verso. RG brasileiro, INE mexicano e similares precisam dos dois lados.

locale (opcional)

Idioma da UI: en, es ou pt. O default é navigator.language, com fallback para inglês para qualquer coisa não reconhecida.

<veridia-widget locale="es">

accent-color (opcional)

Cor primária de botões, links, contornos de foco e indicadores de progresso. Default #0f172a (slate-900, quase preto) — não azul.

Aceita qualquer cor CSS válida, não só hex. Veja Customização.

<veridia-widget accent-color="#7C3AED">

active-liveness (opcional)

Faz opt-in do desafio de prova de vida ativa RBS-2: um desafio de pose de cabeça e flash reativo emitido pelo servidor, que roda depois da selfie. Desligado por padrão.

<veridia-widget active-liveness="true">

Assim como require-doc-back, os únicos valores que significam desligado são "false" e "0"; qualquer outro valor liga. A presença do atributo sem valor liga.

Duas coisas para planejar:

• O desafio adiciona uma etapa ao fluxo do usuário e leva tempo para ser concluído.
• Ele faz muito mais uploads que o fluxo simples (aproximadamente 20 por verificação). Isso pesa contra o limite de taxa por IP de 100 requisições / 60 s: vários usuários mobile atrás do mesmo endereço CGNAT podem esgotá-lo no meio da captura. Veja Limites de taxa.

Configuração programática

Em vez de atributos, você pode definir o objeto de configuração inteiro em 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,
};

Os nomes das propriedades são camelCase, espelhando os atributos em kebab-case. Definir config re-renderiza imediatamente.

Essa é a melhor opção quando seus valores vêm do estado da aplicação, e a única opção para valores que você prefere não colocar no DOM.

Mudando atributos em tempo de execução

Mudar um atributo observado faz o widget reler todos os atributos e re-renderizar:

widget.setAttribute('locale', 'pt');
widget.setAttribute('accent-color', '#10B981');

Não misture config com mudanças de atributo

Os atributos são a fonte de verdade. Tocar em qualquer atributo observado reconstrói a configuração apenas a partir dos atributos — tudo que você definiu pelo setter config é descartado nesse instante, inclusive publishableKey.

A falha na prática: você configura o widget com widget.config = {...}, depois troca o idioma com setAttribute('locale', 'pt'). A chave agora está vazia, o usuário aperta iniciar, e o fluxo morre com invalid_api_key e uma tela de "mal configurado" que te manda auditar um dashboard onde não há nada errado.

Escolha um mecanismo. Se você configura programaticamente, troque o idioma atribuindo um novo objeto config, não definindo um atributo.

Mudanças de configuração não resetam a máquina de estados. Mude country ou document-type antes de o usuário começar a capturar — mudanças no meio do fluxo não alteram retroativamente as etapas já feitas.

Múltiplos widgets na mesma página

Várias instâncias podem coexistir (solicitante e fiador, por exemplo). Cada uma mantém sua própria configuração, câmera e 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>

O face-api.js é carregado uma única vez globalmente pela tag de script — não há penalidade de carregamento por instância. Um exemplo completo está em Exemplos.

Tamanho do payload

Medido no build atual:

Asset	Tamanho	Quando
face-api.js	~1,33 MB	No carregamento da página
veridia-widget.min.js	~45 KB	No carregamento da página
Modelo de detecção de rosto (tiny_face_detector)	~196 KB	Sob demanda, na primeira captura

Cerca de 1,6 MB no total com cache frio, depois em cache no navegador. Um modelo é carregado, não o conjunto completo do face-api.

Se você leu um número como 20 MB em uma versão anterior desta página, ele estava errado por mais de dez vezes — vale reconsiderar se esse número descartou o widget para um público com restrição de dados.

Estilo e dimensionamento

O widget renderiza em um Shadow DOM, então o CSS da sua página não alcança o interior dele e o CSS dele não vaza para fora. A superfície de customização é accent-color, locale, a caixa do element hospedeiro, e a extensão por subclasse.

O card interno é limitado a max-width: 440px e não define altura mínima de contêiner. Detalhes completos, incluindo extensão por subclasse, estão em Customização.

Eventos e códigos de erro

O widget emite dois eventos, veridia:complete e veridia:error. A lista completa de códigos de erro está em Eventos.

Se você está procurando códigos como errorInvalidKey ou errorBlurry, eles nunca foram códigos de erro — são nomes internos de strings de tradução que uma versão anterior desta página publicou por engano. Os códigos reais são camera_denied, camera_unavailable, upload_failed, api_unreachable, invalid_api_key, insufficient_credits, rate_limited, user_cancelled e internal_error.

Próximos passos

• Eventos — formatos dos eventos e a tabela completa de códigos de erro.
• Customização — cor de destaque, idioma, dimensionamento, subclasses.
• Instalação — configuração específica por framework.
• Referência da API — a API server-side que retorna vereditos.