6. Integrar

Emita a sdkUrl no seu backend e monte o widget de verificação na sua página.

Ao final deste passo o fluxo de verificação abre dentro da sua página e os eventos da sessão chegam ao seu código.

A integração tem duas metades, e a ordem importa: o seu backend cria a verificação e recebe a sdkUrl; o seu front-end recebe essa sdkUrl e monta o widget. O navegador do titular nunca toca na chave de API.

Pré-requisitos

• Os passos 1 a 5 concluídos: integração criada, fluxo Publicado, origem Verificada, chave de API com escopo de criar verificação e webhook cadastrado.

Metade 1 — o seu backend emite a sdkUrl

A criação de verificações pela API ainda não está liberada. O contrato abaixo é o implementado no produto e não vai mudar de forma silenciosa; a liberação está descrita em criar verificações.

O seu backend chama a porta de criação com a chave de API no header x-api-key:

Criar a verificação

curl -X POST '<URL_BASE_DA_API>/public/verifications' \
  -H 'x-api-key: <SUA_CHAVE_DE_API>' \
  -H 'content-type: application/json' \
  -d '{
    "schema_version": "1.0",
    "document": { "type": "cpf", "number": "000.000.000-00" },
    "ref_id": "pedido-4471"
  }'

O corpo aceita apenas os campos abaixo, e recusa qualquer outro com 400:

Campo	Obrigatório	O que é
schema_version	sim	sempre "1.0"
document	sim	{ "type": "cpf", "number": "..." }. O CPF entra com ou sem máscara
ref_id	não	o seu identificador do pedido. É a chave da idempotência
flow_public_id	não	ausente usa o fluxo publicado padrão da integração
integration_origin_public_id	não	ausente cria sem pino de origem

A resposta é 201 quando a verificação nasce e 200 quando o mesmo ref_id devolve a que já existe:

Resposta

{
  "schema_version": "1.0",
  "verification": {
    "public_id": "<uuid>",
    "status": "pending",
    "expires_at": "2026-09-01T18:30:00.000Z"
  },
  "entry": {
    "kind": "web",
    "url": "https://verify.legitimuz.com/#v=<uuid>"
  }
}

A sdkUrl é o entry.url. Entregue esse valor ao seu front-end e nada mais.

O entry.url carrega a credencial da verificação no fragmento (#v=...). Trate-a como segredo: não logue, não mande para tag manager, não persista. Ela vale por tempo limitado e para uma única verificação.

Origem nativa recebe entry.kind: "native" com o public_id direto, em vez da URL — o app o entrega ao SDK nativo por canal seguro.

Metade 2 — a sua página monta o widget

O Web SDK é carregado pelo CDN e fica disponível como window.Legitimuz:

<script src="https://sdk.legitimuz.com/v1/websdk.js"></script>

A URL v1 é evergreen: serve sempre a última versão sem breaking change.

Os pacotes @legitimuz/websdk e @legitimuz/websdk-react publicam no npm no lançamento. Até lá, o CDN é a via disponível, e é a que os exemplos abaixo usam.

O widget renderiza dentro de um elemento seu e ocupa 100% da altura dele. Sem altura, o widget existe na página e não aparece.

O menor caminho completo, sem framework nenhum:

<div id="kyc-widget" style="height: 640px"></div>

<script src="https://sdk.legitimuz.com/v1/websdk.js"></script>
<script>
  const handle = window.Legitimuz.mount({
    sdkUrl: "<SUA_SDK_URL>",
    target: document.getElementById("kyc-widget"),
    onReady: () => console.info("widget pronto"),
    // "o fluxo terminou", não "deu certo": status é "submitted" ou "abandoned"
    onComplete: (result) => console.info("fim:", result.status),
    onError: (error) => console.error(error.code, error.user_message),
  });
</script>

mount() devolve um handle com destroy() e a promise ready. Chame destroy() ao remover o widget da página: é o que encerra a câmera.

Escolha o seu framework

Cada guia abaixo é completo e traz a armadilha própria daquele framework — o <StrictMode> no React, a estratégia de carregamento no Next.js, o ngAfterViewInit no Angular.

Vanilla JS

Uma tag script e nada mais, sem passo de build.

React

Um hook que monta uma vez só, mesmo sob StrictMode.

Next.js

App Router, com a página seguindo Server Component.

Vue

Composable com onMounted e onUnmounted.

Angular

Componente standalone com os callbacks como @Output.

O SDK também expõe o custom element <legitimuz-websdk>, para quem preferir montar declarativamente. Só nesse caso o Vue precisa de isCustomElement e o Angular de CUSTOM_ELEMENTS_SCHEMA — pelo mount() dos exemplos acima, nenhum dos dois é necessário.

Confira que funcionou

A primeira tela do fluxo aparece dentro do container e o onReady dispara. Se nada aparecer em 15 segundos, o onError recebe o código 6005.

A lista completa de opções está em opções do mount(), o catálogo de eventos em eventos e os códigos em tratamento de erros.

Quando não funciona

Nada aparece e o onError recebe 6005

O widget não sinalizou ready dentro do tempo limite. As causas mais comuns:

• a origem da sua página não está Verificada na integração — o navegador recusa o iframe sem avisar a sua página. Volte ao passo 3;
• o fluxo não está Publicado. Volte ao passo 2;
• a sdkUrl expirou. Emita outra.

O campo context.likelyCauses do erro lista as hipóteses.

O onError recebe 6003 ou 6004

Falta sdkUrl ou target (6003), ou a sdkUrl não é a URL absoluta esperada (6004) — normalmente porque o backend entregou o objeto entry inteiro em vez do entry.url. O campo context.param aponta qual opção corrigir.

A chamada de criação responde 403

A chave de API não tem o escopo de criar verificação. Volte ao passo 4 e confira Escopo da chave.

Outros ambientes

WebView iOS e Android

Abrir o fluxo dentro de uma WebView e liberar a câmera e o microfone.

Sem o Web SDK

Escrever o iframe você mesmo, e o que você deixa de receber ao fazer isso.

Próximo passo

7. Testar

Rode a jornada ponta a ponta e veja a decisão chegar no seu webhook.