Guia rápido

A integração do enriquecimento do Zarv ID v3 tem 5 passos. Cada um aponta para a página com os detalhes.

1. Autenticar        POST /api/v1/authentication
2. Criar             POST /api/v3/enrichments
3. Aguardar          webhook  ou  GET /api/v3/enrichments/{id}
4. Consultar         GET  /api/v3/enrichments/{id}
5. Buscar módulos    GET  /api/v3/enrichments/{id}/modules/{module}

Antes de começar

Peça ao time da Zarv as credenciais da API e os perfis do seu workspace (um perfil PF para CPF, um perfil PJ para CNPJ). O perfil é definido pelo seu contrato e diz quais módulos e datasets rodam.

• Quais perfis eu tenho? GET /api/v3/profiles lista os perfis, com o profileId de cada um.
• Quais módulos e datasets cada perfil traz? GET /api/v3/profiles/{id} mostra o dataset (a versão) de cada módulo.
• Qual o formato dos dados? Datasets documenta cada módulo, PF e PJ, campo a campo e com exemplo.

1. Autentique

Troque usuário e senha por um token JWT em POST https://services.zarv.com/api/v1/authentication e envie Authorization: Bearer <accessToken> em todas as requisições seguintes. O token dura poucos minutos: renove com o refreshToken.

→ Autenticação

2. Crie o enriquecimento

Envie o document (CPF ou CNPJ) e o profileId. Os módulos que rodam são os do perfil, definidos no seu contrato. Mande também um Idempotency-Key único por consulta, para que um retry não vire uma segunda consulta cobrada.

curl -X POST "https://services.zarv.com/api/v3/enrichments" \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4e2a-9c3f-0a1b2c3d4e5f" \
  -d '{ "document": "111.444.777-35", "profileId": "8f14e45f-ceea-4e7a-9c1a-2b3c4d5e6f70" }'

A requisição espera até 25 segundos. Se terminar a tempo, a resposta é 200 com todos os dados e você pode pular para o passo 4. Se não, é 202 com o id do enriquecimento.

→ POST /api/v3/enrichments · Idempotência

3. Aguarde: webhook ou polling

Escolha um dos dois:

• Webhook: informe um callback na criação e receba um POST assinado no seu endpoint quando o enriquecimento terminar. → Webhook
• Polling: consulte GET /api/v3/enrichments/{id} respeitando o header Retry-After até o status ser COMPLETED ou FAILED. → Espera síncrona e polling

4. Consulte o enriquecimento

GET /api/v3/enrichments/{id} devolve o estado e, em modules, cada módulo que rodou com o dataset que respondeu e o seu status:

{
  "id": "enr_0199a0b2-7c1e-7d4a-9f0e-3b1c2d4e5f60",
  "status": "COMPLETED",
  "modules": {
    "profile": { "dataset": "person-profile-2.0", "status": "ok" },
    "lawsuits": { "dataset": "person-lawsuits-2.0", "status": "ok" }
  }
}

Cada chave de modules é um módulo que você pode buscar no passo 5.

5. Busque os dados de cada módulo

Faça uma requisição por módulo e agregue as respostas do seu lado:

GET /api/v3/enrichments/{id}/modules/profile
GET /api/v3/enrichments/{id}/modules/finance
GET /api/v3/enrichments/{id}/modules/lawsuits
GET /api/v3/enrichments/{id}/modules/related

Cada resposta traz os dados do módulo exatamente como o dataset os publica. Um módulo que ainda não terminou responde 409 module_not_ready.

Prefere tudo de uma vez? Use GET /api/v3/enrichments/{id}?include=data, ou ?include=profile,lawsuits para só alguns módulos.

→ GET /api/v3/enrichments/{id}/modules/{module} · Dados por módulo · Datasets

Próximos passos

• Visão geral: ciclo de vida, status, cobrança e erros.
• Limites de uso: 50 requisições por segundo e como tratar o 429.
• Referência da API: todas as rotas e campos.