Criação de Verificação

A criação de uma verificação no motor novo (engine) é assíncrona: o POST /api/v2/verifications valida o payload, enfileira a verificação e responde imediatamente com status CREATED. O resultado consolidado é obtido depois via GET /api/v2/verifications/{id} (polling) ou pelo webhook de callback.

Para rotear ao motor novo, envie profileId (o ID do profile de scoring). Sem profileId, a requisição segue o fluxo legado.

Campos do payload

Nível raiz

Campo	Tipo	Obrigatório	O que faz
nationalId	string	sim	CPF (11 dígitos) ou CNPJ (14 dígitos) a verificar. Define a entidade (PF/PJ).
profileId	string	não	Profile de scoring aplicado. Presente → roteia para o motor novo; ausente → fluxo legado.
input	array	não	Dados do caso para a análise de IA ({attribute, value, kind}): fatos (context) ou declarações a validar (declared). Ver input.
callback	object	não	Webhook chamado quando a verificação chega a COMPLETED/FAILED. Ver Webhook.
metadata	object	não	Dados livres devolvidos no payload do webhook (rastreio interno).

verifications

Bloco de configuração dos módulos — cada flag liga/ajusta uma etapa do pipeline.

Campo	Tipo	O que ativa
ia.resume	boolean	Gera o resumo por IA e a decisão do autopilot, uma vez, ao fim do processamento. É a única condição: sem ia.resume, nenhum dos dois roda. Pode ser ligado depois, num PATCH ou no PUT de reprocessamento.
finance.restrictions	boolean	Consulta de restrições financeiras (pendências/negativações básicas).
finance.advanced	boolean	Módulo financeAdvanced — dados avançados de crédito, protestos, dívidas e cheques.
faceRecognition	object	Biometria facial. Envie imageURL (ou image base64) para validar a face do titular.
cnh	object	Validação de CNH via OCR (Document AI). Envie imageURL ou imageBase64 do documento.
source	string	Origem da solicitação (API/UI). Default API.
force	boolean	Reprocessa ignorando cache — força nova consulta às fontes externas.
modules	array	Seleção modular (exclusivo do motor): {name, enabled}. Roda só o que vier com enabled: true, mais o módulo profile, que sempre roda. O profile decide o que pode rodar: um name fora do catálogo ou desabilitado no profile retorna 400.

entity (PERSON/COMPANY) não é enviado no request — o motor infere pelo nationalId e devolve na resposta.

input

Dados do caso que a análise de IA leva em conta. Os nomes dos atributos são livres, em qualquer idioma: a IA identifica o dado pelo significado (renda, salário e declaredIncome são o mesmo dado). Não existe lista fixa de atributos.

"input": [
  { "attribute": "aluguel", "value": "2500", "kind": "context" },
  { "attribute": "renda", "value": "8000", "kind": "declared" },
  { "attribute": "endereço", "value": "Rua X, 10 - Florianópolis/SC", "kind": "declared" }
]

O kind diz o que a IA faz com cada atributo:

kind	O que é	Como a IA usa	Autopilot
context	Fato do caso, informado por quem integra.	Toma o valor como verdade. Nunca o confere com os dados encontrados.	É fato: os critérios do profile o avaliam como qualquer dado encontrado (ex.: reprovar se o aluguel passar de 30% da renda).
declared (default)	Declaração a validar.	Compara com os dados encontrados e devolve match, partial ou mismatch.	É declaração: os critérios podem citar o valor declarado ou a conferência dele, mas nunca o tratam como fato.

context só para o que a sua operação garante

Um atributo context é tomado como verdade e entra nos critérios do autopilot como fato. Use-o só para dados que a sua própria operação garante, como o valor do aluguel do imóvel, o produto contratado ou a finalidade. Todo valor digitado ou enviado pelo usuário final (renda, endereço, e-mail, telefone informados num cadastro) deve ir como declared, que é o default. Esta classificação é responsabilidade de quem integra: o Zarv ID não tem como saber de onde veio o valor.

input no autopilot

O autopilot decide pelos critérios de reprovação e de análise manual configurados no profile, em texto livre; a aprovação é o que sobra quando nenhum critério casa. Esses critérios podem citar atributos do input dos dois tipos:

Critério no profile	Usa
"Reprovar se o aluguel passar de 30% da renda"	o aluguel (context) como fato, contra a renda encontrada
"Análise manual se a renda declarada passar de R$ 50 mil"	o valor da renda (declared) como declaração
"Reprovar se o endereço declarado não conferir"	a conferência do endereço (declared)

Um critério sobre o dado em si ("reprovar se a renda for menor que 2 salários mínimos") é avaliado sobre o dado encontrado, nunca sobre o declarado. Sem critério que o cite, o input sozinho não muda a decisão.

Sem kind, o atributo vale como declared: só vira fato o que quem integra marcar como context. Um kind diferente de context ou declared retorna 400.

Limites, aplicados no POST e no lote:

• até 20 atributos; os excedentes são descartados;
• até 512 caracteres por value; o restante é cortado;
• atributo repetido: vale o último;
• item sem attribute é descartado;
• valor de exemplo (entre < e >, como <preencher>) ou sem letra nem dígito não chega à IA e sai como not_evaluated.

O resultado sai em finalSummary.inputChecks do resumo por IA, uma entrada por atributo, na ordem em que veio:

status	Significado
match	O declarado confere com os dados encontrados.
partial	Parte do declarado confere e parte diverge.
mismatch	O declarado não confere.
context	Atributo context: usado como fato, não conferido.
not_evaluated	Nenhum módulo tinha o dado para conferir, ou o valor foi descartado.

Diferença só de formato (acento, caixa, máscara, abreviação) não é divergência, e declarar com menos detalhe que o cadastro (só a cidade de um endereço) conta como match.

Máquina de estados

Toda verificação percorre os estados abaixo. COMPLETED e FAILED são terminais; o webhook (se configurado) dispara ao alcançá-los, e só neles.

                        ┌───────────┐
                        │  CREATED  │   POST aceito e enfileirado
                        └─────┬─────┘
                              │  consumer do motor inicia
                              ▼
                        ┌────────────┐
                 erro   │ PROCESSING │   módulos do motor rodando
             ┌──────────┤            │
             │          └─────┬──────┘
             │                │
             │            ia.resume na verificação?
             │          sim ──┴── não
             │           │         │
             │           ▼         │
             │    ┌────────────┐   │
             │    │ ANALYZING  │   │   motor ok, resumo de IA sendo gerado
             │    │ (IA)       │   │
             │    └─────┬──────┘   │
             │          │          │
             │          ▼          ▼
             │        ┌───────────────┐
             │        │   COMPLETED   │   terminal (sucesso)
             │        └───────────────┘
             ▼
        ┌───────────┐   nova tentativa automática
        │ RETRYING  ├──────────────► PROCESSING
        └─────┬─────┘
              │  24h após a criação sem concluir
              ▼
        ┌───────────┐
        │  FAILED   │   terminal (falha)
        └───────────┘

Uma falha no processamento leva a RETRYING, não a FAILED: a Zarv tenta de novo automaticamente, sem novo webhook e sem ação sua. Se a verificação não concluir em até 24h após a criação, ela passa a FAILED, que é definitivo, e só então o webhook de falha é enviado, uma única vez.

Fluxos com validação de CNH podem passar por um estado intermediário CNH_EXTRACT durante a extração do documento (Document AI) antes de PROCESSING.

Estados

Status	Terminal	Descrição
CREATED	não	Verificação aceita e enfileirada. Resposta imediata do POST.
CNH_EXTRACT	não	Extração de dados da CNH via OCR (apenas fluxos com cnh).
PROCESSING	não	Motor executando os módulos (perfil, finanças, processos, relacionados, etc.).
ANALYZING	não	Motor concluído; resumo por IA sendo gerado. O endpoint /ai-summary já responde nesse estado (fallback). Verificações sem ia.resume pulam direto para COMPLETED.
COMPLETED	sim	Verificação concluída com resultado consolidado disponível.
RETRYING	não	O processamento falhou e será repetido automaticamente. Não dispara webhook.
FAILED	sim	Falha definitiva: a verificação não concluiu em até 24h após a criação. O motivo vem em failure.

Consulte a estrutura da resposta para o formato do dossiê retornado em COMPLETED.