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.

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.

Antes de começar

Este guia parte do guia rápido: 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.

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.

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:

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

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:

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

GET

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.

3. Aplique o financeiro avançado

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

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

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 } } }),
});

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:

{
  "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: da autenticação à primeira verificação.
• Criação de Verificação: todos os campos e a máquina de estados.
• Webhook de Verificação: cabeçalhos, reenvio e payload.