Guia rápido
Este guia vai do zero à primeira verificação de identidade: autenticar, escolher o perfil, criar a verificação e receber o resultado. Você precisa de um usuário Zarv com as roles id-create, id-list e id-view.
1. Autenticar POST /api/v1/authentication
2. Escolher o perfil GET /api/v2/profiles?kind=verification
3. Criar POST /api/v2/verifications
4. Receber webhook ou GET /api/v2/verifications/{id}Antes de começar
Peça ao time da Zarv as credenciais da API e os perfis do seu workspace. O perfil define quais módulos e regras de score rodam na verificação, e cada um atende uma entidade: você precisa de um perfil PF para verificar CPF e de um perfil PJ para verificar CNPJ.
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.
curl -X POST "https://services.zarv.com/api/v1/authentication" \
-H "Content-Type: application/json" \
-d '{"username": "[email protected]", "password": "sua_senha"}'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();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. Escolha o perfil
Liste os perfis de verificação do seu workspace:
curl "https://services.zarv.com/api/v2/profiles?kind=verification" \
-H "Authorization: Bearer $ACCESS_TOKEN"A resposta é uma lista. Cada item traz o id, que é o profileId da verificação, o nome, a entidade que o perfil atende (pf para CPF, pj para CNPJ) e se ele é o padrão do workspace para essa entidade (isDefault):
[
{
"id": "22222222-0000-0000-0000-000000000001",
"name": "Pessoas 1.1",
"entityType": "pf",
"kind": "verification",
"isDefault": true,
"active": true
}
]Use um perfil verification da mesma entidade do documento. Para pegar direto o perfil padrão de uma entidade, use GET /api/v2/profiles/default/{pf|pj}. Para mudar os módulos ou as regras de um perfil, ou criar um novo, fale com o time da Zarv.
3. Crie uma verificação
Envie o CPF ou CNPJ a verificar e o profileId do perfil escolhido no passo 2. A criação é assíncrona: a API responde na hora com um id e o status CREATED, e o resultado fica pronto depois.
curl -X POST "https://services.zarv.com/api/v2/verifications" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"nationalId": "11111111111",
"profileId": "22222222-0000-0000-0000-000000000001",
"verifications": { "finance": { "restrictions": true }, "ia": { "resume": true } },
"callback": { "url": "https://sua-api.com/webhooks/zarv", "method": "POST" },
"metadata": { "pedidoId": "12345" }
}'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: "11111111111",
profileId: "22222222-0000-0000-0000-000000000001",
verifications: { finance: { restrictions: true }, ia: { resume: true } },
callback: { url: "https://sua-api.com/webhooks/zarv", method: "POST" },
metadata: { pedidoId: "12345" },
}),
});
const { id } = await res.json();res = requests.post(
"https://services.zarv.com/api/v2/verifications",
headers={"Authorization": f"Bearer {access_token}"},
json={
"nationalId": "11111111111",
"profileId": "22222222-0000-0000-0000-000000000001",
"verifications": {"finance": {"restrictions": True}, "ia": {"resume": 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",
"profileId": "22222222-0000-0000-0000-000000000001",
"nationalId": "11111111111",
"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.
4. Receba o resultado
A verificação passa por CREATED → PROCESSING → COMPLETED (ou FAILED, depois de até 24h de novas tentativas em RETRYING); veja a criação de verificação para a máquina de estados completa. Há duas formas de saber que terminou.
Webhook (recomendado)
Como você mandou callback.url no passo 3, 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:
curl "https://services.zarv.com/api/v2/verifications/805181ca-2956-49e1-81bb-93d1792d269d" \
-H "Authorization: Bearer $ACCESS_TOKEN"const res = await fetch(
`https://services.zarv.com/api/v2/verifications/${id}`,
{ headers: { Authorization: `Bearer ${accessToken}` } },
);
const verification = await res.json();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 result do perfil e os módulos que você pediu (e o resumo por IA, se habilitado).
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.
- Zarv ID v3 — a nova versão, por enquanto só com enriquecimento (guia rápido).
- Setup — a página densa, escrita para agentes de código.
- Limites de uso — cota por workspace e como tratar o 429.