---
url: https://developers.zarv.com/api/decision-engine/creation.md
---
# 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}`](/api/decision-engine/getVerification) (polling) ou pelo [webhook de callback](/api/decision-engine/webhook).

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](/api/decision-engine/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](/api/decision-engine/structure) para o formato do dossiê retornado em `COMPLETED`.