> ## Documentation Index
> Fetch the complete documentation index at: https://documentacao.legitimuz.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tip>
  Leva cerca de 15 minutos. Se você prefere que um agente de IA faça a integração, veja
  [Legitimuz + IA](/ai/overview).
</Tip>

## O que você vai precisar

* Acesso ao [dashboard](https://painel.legitimuz.com) 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](https://painel.legitimuz.com/integrations) 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.

<Card title="Integrações em detalhe" icon="puzzle" href="/platform/integrations" horizontal>
  Ambientes, origens, chaves e aparência.
</Card>

## 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](https://painel.legitimuz.com/flows) 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](https://painel.legitimuz.com/support).

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

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

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

<Card title="Webhooks em detalhe" icon="webhook" href="/webhooks/introduction" horizontal>
  Eventos, segurança, retentativa e histórico de entregas.
</Card>

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

```bash theme={null}
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:

```json theme={null}
{
  "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>"
  }
}
```

<Card title="Referência completa" icon="terminal-2" href="/api/create-verification" horizontal>
  Todos os campos, os códigos de resposta e a idempotência por `ref_id`.
</Card>

## 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](/guides/web/vanilla-js), ou dentro do seu app com os [SDKs nativos](/sdks/android). 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`:

```json theme={null}
{
  "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.

<Warning>
  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](/webhooks/security).
</Warning>

## Confira que funcionou

1. A verificação aparece em [Verificações](https://painel.legitimuz.com/verifications) 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

<Columns cols={2}>
  <Card title="Abrir na web" icon="browser" href="/guides/web/vanilla-js">
    React, Next.js, Vue, Angular ou HTML puro.
  </Card>

  <Card title="Abrir no app" icon="device-mobile" href="/sdks/android">
    Android, iOS e React Native.
  </Card>

  <Card title="Todos os eventos" icon="bolt" href="/webhooks/events">
    Os sete eventos da jornada, com o corpo de cada um.
  </Card>

  <Card title="Ir para produção" icon="rocket" href="/start/production">
    O checklist antes da primeira pessoa real.
  </Card>
</Columns>