---
url: https://developers.zarv.com/api/id-v2/financeiro-avancado.md
description: >-
  Como aplicar o financeiro avançado a uma verificação já concluída no Zarv ID
  v2: PATCH na verificação, aviso por webhook e resultado pelo GET.
---

# Fluxo async financeiro avançado

O financeiro avançado pode ser pedido **depois** da verificação: crie a
verificação sem ele, espere `COMPLETED` e mande um `PATCH` que liga
`finance.advanced`. Só o módulo `financeAdvanced` roda; os módulos que já
rodaram não são refeitos nem cobrados de novo.

```text
1. Criar        POST  /api/v2/verifications            → 201, CREATED
2. Receber      webhook (COMPLETED)  +  GET /api/v2/verifications/{id}
3. Aplicar      PATCH /api/v2/verifications/{id}       → 202, PROCESSING
4. Receber      webhook (COMPLETED)  +  GET /api/v2/verifications/{id}
```

Toda chamada responde na hora; o trabalho roda numa fila. O resultado nunca
vem na resposta do `POST` ou do `PATCH`: o webhook avisa que terminou, e o
`GET` traz os dados.

::: tip Antes de começar
Este guia parte do [guia rápido](/api/id-v2/quickstart): token, perfil e
criação funcionam igual. Além disso, o **perfil** da verificação precisa ter o
módulo `financeAdvanced` habilitado, e o seu workspace precisa de um contrato
ativo. Fale com o time da Zarv se faltar algum dos dois.
:::

Todos os exemplos usam `https://services.zarv.com`, o host de produção, e
`$ACCESS_TOKEN` obtido como no [passo 1 do guia rápido](/api/id-v2/quickstart#_1-obtenha-um-token).

## 1. Crie a verificação sem o financeiro avançado

Igual ao guia rápido, com `finance.advanced: false`. Mande `callback` para
receber os avisos e `metadata` para amarrar a verificação ao seu pedido.

```sh
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": { "advanced": false } },
    "callback": { "url": "https://sua-api.com/webhooks/zarv", "method": "POST" },
    "metadata": { "pedidoId": "12345" }
  }'
```

Resposta `201`, com o `id` que você usa nos passos seguintes:

```json
{
  "id": "805181ca-2956-49e1-81bb-93d1792d269d",
  "profileId": "22222222-0000-0000-0000-000000000001",
  "nationalId": "11111111111",
  "status": "CREATED"
}
```

::: info Perfil com financeiro avançado obrigatório
Se o perfil exige o financeiro avançado em toda verificação, ele já roda aqui,
e o `PATCH` do passo 3 não faz nada.
:::

## 2. Espere o webhook e busque o resultado

A verificação passa por `CREATED` → `PROCESSING` → `COMPLETED`. O `PATCH` do
passo 3 é recusado com `409` enquanto ela está em `PROCESSING`, então espere o
aviso de `COMPLETED`.

### Webhook

A Zarv chama o seu `callback.url` quando a verificação chega a um estado final,
`COMPLETED` ou `FAILED`:

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

* O corpo **não traz o resultado**: é só o aviso. Os dados vêm do `GET`.
* `metadata` volta como você mandou na criação.
* Os `headers` do `callback` são reenviados como estão: é onde vai o segredo
  para você autenticar a chamada.
* A URL precisa ser `https` e pública.
* O reenvio é curto: até 2 novas tentativas, em poucos segundos. Se o seu
  endpoint estiver fora do ar, o aviso se perde, então tenha o `GET` como rede
  de segurança.

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

### GET

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

Com `status` em `COMPLETED`, o corpo traz o `result` do perfil e os módulos que
rodaram. Sem webhook, consulte em intervalos crescentes; consultar em rajada
gasta a sua [cota](/api/limits).

## 3. Aplique o financeiro avançado

Com a verificação em `COMPLETED`, ligue `finance.advanced` com um `PATCH`:

::: code-group

```sh [Bash]
curl -X PATCH "https://services.zarv.com/api/v2/verifications/805181ca-2956-49e1-81bb-93d1792d269d" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "verifications": { "finance": { "advanced": true } } }'
```

```js [Node.js]
await fetch(`https://services.zarv.com/api/v2/verifications/${id}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ verifications: { finance: { advanced: true } } }),
});
```

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

:::

A mesma coisa pela lista de módulos:

```json
{
  "verifications": {
    "modules": [{ "name": "financeAdvanced", "enabled": true }]
  }
}
```

Use uma forma só. `finance.advanced: false` junto de `financeAdvanced` ligado em
`modules` volta `400 conflicting_module_request`.

Resposta `202`, com a verificação já em `PROCESSING`. Daqui em diante é o
passo 2 de novo.

* **O que roda:** só o `financeAdvanced`. O score final é recalculado com ele.
* **Cobrança:** o financeiro avançado é cobrado como adicional, a não ser que o
  seu contrato o inclua no perfil.
* **Repetir o `PATCH`** numa verificação que já tem o módulo não faz nada: não
  roda nem cobra.
* **No mesmo `PATCH`** você pode trocar `callback` e `metadata`, se o aviso do
  adicional deve ir para outro endpoint.
* **Não use `PUT`** para isso: `PUT /api/v2/verifications/{id}` refaz a
  verificação inteira, com todos os módulos.

## 4. Receba o resultado com o financeiro avançado

O webhook dispara de novo, com o mesmo `id`, quando o `financeAdvanced`
termina. Trate os avisos como idempotentes: o mesmo `id` chega uma vez por
execução.

No `GET`, o resultado aparece em `person.financeAdvanced` (CPF) ou
`business.financeAdvanced` (CNPJ), e `verifications.finance.advanced` passa a
`true`.

O financeiro avançado depende de um bureau externo. Se ele estiver fora do ar,
a verificação fica em `RETRYING`, sem webhook, e a Zarv tenta de novo sozinha.
Se não voltar em 24 horas, ela vai para `FAILED`, e o webhook avisa com o
motivo em `failure`.

## Erros do PATCH

Os erros trazem `error` e um `code` estável no corpo. Decida pelo `code`, não
pelo texto.

| HTTP  | `code`                       | Quando                                                       | O que fazer                       |
| ----- | ---------------------------- | ------------------------------------------------------------ | --------------------------------- |
| `409` | `still_processing`           | A verificação ainda está em `PROCESSING`                     | Esperar o webhook de `COMPLETED`  |
| `400` | `module_disabled_in_profile` | O perfil tem o `financeAdvanced` desligado                   | Pedir ao time da Zarv para ativar |
| `400` | `module_not_in_profile`      | Nome de módulo errado, ou perfil de outra entidade           | Conferir o nome e o perfil        |
| `400` | `conflicting_module_request` | `finance.advanced: false` com `financeAdvanced` em `modules` | Mandar uma forma só               |
| `402` |                              | Workspace sem contrato ativo                                 | Falar com o time da Zarv          |
| `503` |                              | Não foi possível confirmar o contrato                        | Tentar de novo depois             |
| `404` | `not_found`                  | `id` inexistente ou de outro workspace                       | Conferir o `id` e o token         |

## Próximos passos

* **[Guia rápido](/api/id-v2/quickstart)**: da autenticação à primeira verificação.
* **[Criação de Verificação](/api/id-v2/creation)**: todos os campos e a máquina de estados.
* **[Webhook de Verificação](/api/id-v2/webhook)**: cabeçalhos, reenvio e payload.