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 de caso declarados pelo solicitante (`{attribute, value}`). Servem de contexto para a análise de IA (comparados com os dados encontrados).
`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/veredito por IA. Só ocorre se o profile tiver IA habilitada; este bloco sobrepõe por execução.
`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	Override modular (exclusivo do motor): `{name, enabled}` liga/desliga módulos do profile nesta verificação. Cada `name` deve existir no catálogo do profile; módulos não listados usam o default.

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

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.

text

                        ┌───────────┐
                        │  CREATED  │   POST aceito e enfileirado
                        └─────┬─────┘
                              │  consumer do motor inicia
                              ▼
                        ┌────────────┐
                 erro   │ PROCESSING │   módulos do motor rodando
             ┌──────────┤            │
             │          └─────┬──────┘
             │                │
             │       profile com IA e sem deferAutopilot?
             │          sim ──┴── não
             │           │         │
             │           ▼         │
             │    ┌────────────┐   │
             │    │ ANALYZING  │   │   motor ok, resumo de IA sendo gerado
             │    │ (IA)       │   │
             │    └─────┬──────┘   │
             │          │          │
             │          ▼          ▼
             │        ┌───────────────┐
             │        │   COMPLETED   │   terminal (sucesso)
             │        └───────────────┘
             ▼
        ┌───────────┐
        │  FAILED   │   terminal (falha)
        └───────────┘

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 pulam direto para `COMPLETED`.
`COMPLETED`	sim	Verificação concluída com resultado consolidado disponível.
`FAILED`	sim	Falha no processamento.

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

Criação de Verificação ​

Campos do payload ​

Nível raiz ​

verifications ​

Máquina de estados ​