---
url: https://developers.zarv.com/api/id-v3/quickstart.md
description: >-
  Integre o enriquecimento do Zarv ID v3 em 5 passos: autentique, crie o
  enriquecimento, aguarde por webhook ou polling e busque os dados de cada
  módulo.
---

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

```text
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}
```

::: tip 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`](/api/id-v3/listProfiles) lista os perfis, com o `profileId` de cada um.
* **Quais módulos e datasets cada perfil traz?** [`GET /api/v3/profiles/{id}`](/api/id-v3/getProfile) mostra o dataset (a versão) de cada módulo.
* **Qual o formato dos dados?** [Datasets](/api/id-v3/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](/api/id-v3/authentication)

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

```sh
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`](/api/id-v3/createEnrichment) · [Idempotência](/api/id-v3/#idempotencia)

## 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](/api/id-v3/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](/api/id-v3/#espera-sincrona-e-polling)

## 4. Consulte o enriquecimento

[`GET /api/v3/enrichments/{id}`](/api/id-v3/getEnrichment) devolve o estado e, em `modules`, cada módulo que rodou com o dataset que respondeu e o seu `status`:

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

```text
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}`](/api/id-v3/getEnrichmentModule) · [Dados por módulo](/api/id-v3/#dados-por-modulo) · [Datasets](/api/id-v3/datasets/)

## Próximos passos

* [Visão geral](/api/id-v3/): ciclo de vida, status, cobrança e erros.
* [Limites de uso](/api/id-v3/limits): 50 requisições por segundo e como tratar o `429`.
* [Referência da API](/api/id-v3/reference): todas as rotas e campos.