---
url: https://developers.zarv.com/quickstart.md
---
# Comece em 5 minutos

Este guia vai do zero à primeira verificação de identidade: autenticar, criar a
verificação e receber o resultado. Você precisa de um usuário Zarv com as roles
`id-create` e `id-view` — peça ao time da Zarv se ainda não tiver.

Todos os exemplos usam `https://services.zarv.com`, o host de produção.

## 1. Obtenha um token

Troque usuário e senha por um token de acesso. Faça isso **no seu servidor** —
nunca no navegador.

::: code-group

```sh [Bash]
curl -X POST "https://services.zarv.com/api/v1/authentication" \
  -H "Content-Type: application/json" \
  -d '{"username": "seu.email@empresa.com", "password": "sua_senha"}'
```

```js [Node.js]
const res = await fetch("https://services.zarv.com/api/v1/authentication", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "seu.email@empresa.com",
    password: "sua_senha",
  }),
});

const { accessToken } = await res.json();
```

```py [Python]
import requests

res = requests.post(
    "https://services.zarv.com/api/v1/authentication",
    json={"username": "seu.email@empresa.com", "password": "sua_senha"},
)

access_token = res.json()["accessToken"]
```

:::

A resposta traz `accessToken` e `refreshToken`:

```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 360,
  "refreshExpiresIn": 1800
}
```

::: warning O token dura 6 minutos
Guarde o `accessToken` e reutilize-o enquanto valer. Quando expirar, use o
[refresh](/api/zarv-id/authentication#renovando-um-token-de-acesso) em vez de
reenviar usuário e senha. Autenticar a cada requisição gasta a sua
[cota](/api/limits) à toa.
:::

## 2. Crie uma verificação

Envie o CPF ou CNPJ a verificar. A criação é **assíncrona**: a API responde na
hora com um `id` e o status `CREATED`, e o resultado fica pronto depois.

::: code-group

```sh [Bash]
curl -X POST "https://services.zarv.com/api/v2/verifications" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nationalId": "012345678900",
    "verifications": { "type": "full", "finance": { "restrictions": true } },
    "callback": { "url": "https://sua-api.com/webhooks/zarv", "method": "POST" },
    "metadata": { "pedidoId": "12345" }
  }'
```

```js [Node.js]
const res = await fetch("https://services.zarv.com/api/v2/verifications", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    nationalId: "012345678900",
    verifications: { type: "full", finance: { restrictions: true } },
    callback: { url: "https://sua-api.com/webhooks/zarv", method: "POST" },
    metadata: { pedidoId: "12345" },
  }),
});

const { id } = await res.json();
```

```py [Python]
res = requests.post(
    "https://services.zarv.com/api/v2/verifications",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "nationalId": "012345678900",
        "verifications": {"type": "full", "finance": {"restrictions": True}},
        "callback": {"url": "https://sua-api.com/webhooks/zarv", "method": "POST"},
        "metadata": {"pedidoId": "12345"},
    },
)

verification_id = res.json()["id"]
```

:::

Resposta `201`:

```json
{
  "id": "805181ca-2956-49e1-81bb-93d1792d269d",
  "nationalId": "012345678900",
  "status": "CREATED"
}
```

Guarde o `id`: é por ele que você consulta o resultado. O campo `metadata` é
livre e volta igual no webhook — use para amarrar a verificação ao seu pedido.

## 3. Receba o resultado

A verificação passa por `CREATED` → `PROCESSING` → `COMPLETED` (ou `FAILED`).
Há duas formas de saber que terminou.

### Webhook (recomendado)

Como você mandou `callback.url` no passo 2, a Zarv chama o seu endpoint assim
que a verificação chega a um estado final:

```json
{
  "id": "805181ca-2956-49e1-81bb-93d1792d269d",
  "status": "COMPLETED",
  "metadata": { "pedidoId": "12345" }
}
```

Responda `200` para confirmar o recebimento, e trate o processamento de forma
assíncrona. O payload avisa **que** terminou; os dados vêm na consulta abaixo.

Detalhes de configuração, cabeçalhos e reenvio estão no
[Webhook de Verificação](/api/zarv-id/webhook).

### Consulta direta

Com o `id` em mãos:

::: code-group

```sh [Bash]
curl "https://services.zarv.com/api/v2/verifications/805181ca-2956-49e1-81bb-93d1792d269d" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```js [Node.js]
const res = await fetch(
  `https://services.zarv.com/api/v2/verifications/${id}`,
  { headers: { Authorization: `Bearer ${accessToken}` } },
);

const verification = await res.json();
```

```py [Python]
res = requests.get(
    f"https://services.zarv.com/api/v2/verifications/{verification_id}",
    headers={"Authorization": f"Bearer {access_token}"},
)

verification = res.json()
```

:::

Quando o `status` for `COMPLETED`, o corpo traz o nome do titular, o score e o
resultado dos módulos que você pediu.

::: tip Prefira o webhook ao polling
Se for consultar em loop, espere entre as tentativas e aumente o intervalo a
cada uma. Consultar em rajada gasta a sua [cota](/api/limits) sem acelerar o
resultado.
:::

## Próximos passos

* **[Referência da API](/api/zarv-id/)** — todos os endpoints, campos e exemplos.
* **[Decision Engine](/api/decision-engine/)** — verificação por perfil de
  scoring, com dossiê consolidado e resumo por IA.
* **[Setup](/setup)** — a página densa, escrita para agentes de código.
* **[Limites de uso](/api/limits)** — cota por workspace e como tratar o 429.