Receba sua primeira verificação

Um guia passo a passo para criar uma verificação em sandbox e ver a decisão chegar ao seu backend.

Ao final deste guia você terá criado uma verificação pela API, percorrido a jornada como a pessoa faria e recebido o desfecho por webhook. Tudo em sandbox, sem titular real e sem cobrança.

Leva cerca de 15 minutos. Se você prefere que um agente de IA faça a integração, veja Legitimuz + IA.

O que você vai precisar

• Acesso ao dashboard com permissão de criar integração.
• Um terminal com curl.
• Um endereço público em HTTPS que receba POST. Em desenvolvimento, um túnel local resolve.

Passo 1: crie uma integração em sandbox

1. Abra Integrações e clique em Criar integração.
2. Dê um nome que diga onde ela roda, como Checkout web.
3. Escolha o ambiente Sandbox.

Uma integração reúne as origens, as chaves e os webhooks de um canal seu. O ambiente é definido na criação e não muda depois.

Integrações em detalhe

Ambientes, origens, chaves e aparência.

Passo 2: confirme o fluxo publicado

O fluxo é a sequência de etapas que a pessoa percorre. A Legitimuz publica o fluxo da sua integração na implantação.

1. Abra Fluxos e confirme que existe um fluxo publicado para a sua integração.
2. Anote o public_id dele, se quiser escolher o fluxo na criação. Sem ele, a integração usa o fluxo padrão.

Se não houver fluxo publicado, fale com o suporte.

Passo 3: autorize uma origem

A verificação só abre em domínios e apps autorizados.

1. Na integração, vá em Segurança → Domínios Autorizados e clique em Adicionar Domínio.
2. Informe o domínio onde a verificação vai abrir, como cadastro.exemplo.com.br.
3. Aguarde o status mudar de Aguardando validação para Verificada. A Legitimuz confirma a posse; você não precisa fazer nada nesse intervalo.
4. Anote o public_id da origem. Ele é obrigatório na criação.

Para app nativo, registre um App Bundle em vez de um domínio.

Passo 4: crie uma chave de API

1. Em Segurança → Chaves de API, clique em Nova Chave.
2. Conceda apenas a permissão de criar verificação.
3. Copie o valor agora e guarde no cofre de segredos do seu backend.

A chave aparece uma única vez. Ela nunca vai para o browser, para o app, para o repositório ou para a URL.

Passo 5: cadastre o webhook

1. Em Segurança → Webhooks, clique em Novo Endpoint.
2. Informe a URL do seu endpoint e marque Verificação decidida.
3. Guarde o segredo de assinatura que aparece na criação.

Webhooks em detalhe

Eventos, segurança, retentativa e histórico de entregas.

Passo 6: crie a verificação

Com a chave e o public_id da origem em mãos, chame a API a partir do seu servidor:

curl -X POST https://api.legitimuz.com/public/verifications \
  -H "X-API-Key: $LEGITIMUZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "1.0",
    "ref_id": "pedido-0001",
    "document": { "type": "cpf", "number": "<CPF_DE_TESTE>" },
    "integration_origin_public_id": "<ORIGIN_PUBLIC_ID>"
  }'

A resposta traz a verificação e a entrada da jornada:

{
  "schema_version": "1.0",
  "verification": {
    "public_id": "019f0000-0000-7000-8000-000000000000",
    "status": "not_opened",
    "expires_at": "2026-09-15T14:30:00.000Z"
  },
  "entry": {
    "kind": "web",
    "url": "https://verify.legitimuz.com/#v=<access_credential>"
  }
}

Referência completa

Todos os campos, os códigos de resposta e a idempotência por ref_id.

Passo 7: abra a jornada

Abra entry.url no browser e percorra as etapas como a pessoa faria: selfie, documento, dados.

Num produto real você não redireciona. A verificação abre dentro da sua página com o Web SDK, ou dentro do seu app com os SDKs nativos. A entry.url sai do seu backend e nunca fica fixa no código do cliente.

Passo 8: receba a decisão

Quando a verificação chega ao desfecho, o seu endpoint recebe verification.decided:

{
  "id": "019f0000-0000-7000-8000-000000000001",
  "event": "verification.decided",
  "occurred_at": "2026-09-14T17:30:00.000Z",
  "tenant_public_id": "019f0000-0000-7000-8000-000000000002",
  "resource": {
    "type": "verification",
    "public_id": "019f0000-0000-7000-8000-000000000000"
  },
  "verification": {
    "status": "approved",
    "ref_id": "pedido-0001",
    "decided_at": "2026-09-14T17:29:58.000Z"
  }
}

O ref_id é a chave que você mandou na criação. Use-a para achar o pedido no seu banco.

Confira a assinatura antes de confiar no corpo. Um endpoint que processa qualquer POST aceita um desfecho forjado. O código de conferência está em segurança dos webhooks.

Confira que funcionou

1. A verificação aparece em Verificações com status diferente de not_opened.
2. O seu endpoint registrou uma entrega com o header X-Legitimuz-Event: verification.decided.
3. O ref_id no corpo bate com o pedido do seu banco.

Se a entrega não chegou, a aba Webhooks da integração mostra cada tentativa com o código que o seu servidor devolveu.

Próximos passos

Abrir na web

React, Next.js, Vue, Angular ou HTML puro.

Abrir no app

Android, iOS e React Native.

Todos os eventos

Os sete eventos da jornada, com o corpo de cada um.

Ir para produção

O checklist antes da primeira pessoa real.