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.

Bash

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

Node.js

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

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

Python

import requests

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

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

A resposta traz accessToken e refreshToken:

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

O token dura 6 minutos

Guarde o accessToken e reutilize-o enquanto valer. Quando expirar, use o refresh em vez de reenviar usuário e senha. Autenticar a cada requisição gasta a sua cota à 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.

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" }
  }'

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();

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:

{
  "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:

{
  "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.

Consulta direta

Com o id em mãos:

Bash

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

Node.js

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

const verification = await res.json();

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.

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 sem acelerar o resultado.

Próximos passos

• Referência da API — todos os endpoints, campos e exemplos.
• Decision Engine — verificação por perfil de scoring, com dossiê consolidado e resumo por IA.
• Setup — a página densa, escrita para agentes de código.
• Limites de uso — cota por workspace e como tratar o 429.