--- url: https://developers.zarv.com/api/decision-engine/structure.md --- # Estrutura da Consulta Quando uma verificação chega a `COMPLETED`, o [`GET /api/v2/verifications/{id}`](/api/decision-engine/getVerification) retorna o dossiê consolidado. Este documento descreve a estrutura desse retorno. O corpo tem três partes: **metadados** (identificadores e datas), **`result`** (resultado consolidado do scoring) e o **dossiê da entidade** — em `person` para CPF ou em `business` para CNPJ. ## Metadados | Campo | Descrição | | ------------------------- | ------------------------------------------------------------ | | `id` | ID da verificação (use no polling e no webhook). | | `workspaceId` | Workspace dono da verificação. | | `profileId` | Profile de scoring aplicado. | | `nationalId` | CPF/CNPJ verificado. | | `status` | Estado atual (ver [Criação](/api/decision-engine/creation)). | | `version` | Versão do motor (ex.: `v5`). | | `executedAt` | Início do processamento pelo motor. | | `createdAt` / `updatedAt` | Datas de criação e última atualização. | ## `result` Resultado consolidado do scoring. | Campo | Descrição | | ------------------- | ---------------------------------------------------------------------------------- | | `score` | Score final da verificação. | | `scoreFactor` | Fator de risco derivado do score. | | `rules` | Nomes das regras acionadas (apenas as dos módulos; ajustes/marcadores ficam fora). | | `scoreDistribution` | Peso relativo de cada módulo no score (`{module, percent}`). | | `execution` | Tempos de execução (`startedAt`, `endedAt`, `durationMs`). | | `relatedCount` | Total de pessoas relacionadas encontradas. | ## `person` (CPF) Dossiê do titular pessoa física. | Módulo | Conteúdo | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `profile` | Dados cadastrais, idade, situação fiscal, blacklist (cliente/Zarv), contatos (endereços, e-mails, telefones) e indicadores do titular. | | `finance` | Renda, patrimônio, coleções, programas assistenciais e restrições. `financeAdvanced` traz score de crédito, protestos, dívidas e cheques. | | `lawsuits` | Processos do titular (nível `L1`) com indicadores. `defendant` é o fan-out `L2`: co-réus (pessoas/empresas) e seus processos. | | `related` | Rede pessoal (`personal`) e empresarial (`business`: `ownerships`/`employments`), com indicadores e totais de relacionamentos. | | `archetypes` | Aderência a arquétipos (identificação; não altera o score nesta iteração). | ## `business` (CNPJ) Dossiê da empresa pessoa jurídica. | Módulo | Conteúdo | | -------------------- | ------------------------------------------------------------------------------------------ | | `profile` | Cadastro da empresa: atividades, natureza jurídica, situação fiscal, blacklist e contatos. | | `finance` | Indicadores financeiros da empresa. | | `lawsuits` | Processos da empresa (`L1`) e fan-out `L2` (`defendant`). | | `related` | Relacionamentos empresariais. | | `corporateStructure` | Quadro societário. | | `relationships` | Sócios e pessoas relacionadas. | | `archetypes` | Aderência a arquétipos. | ## Processos (`lawsuits`) O bloco `lawsuits` tem a **mesma estrutura para CPF e CNPJ**, e o **item de processo é idêntico em L1 e L2**. O que muda é o campo `level` (`L1` = processo da própria entidade; `L2` = processo de um co-réu) e `entityType` (`PERSON`/`COMPANY`). Documentar uma vez cobre os quatro casos (L1/L2 × PF/PJ). ### Container | Campo | Descrição | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | `items` | Processos **L1** — da própria entidade verificada (lista de [item de processo](#item-de-processo)). | | `counters` | Contagem por natureza: `total`, `criminal`, `civil`, `labour`, `tax`, `fiscal`, `administrative`, `others`. | | `defendant.person` | Fan-out **L2**: co-réus pessoas físicas e seus processos (ver [Co-réu (L2)](#co-reu-l2)). | | `defendant.company` | Fan-out **L2**: co-réus pessoas jurídicas e seus processos. | | `indicators` | Sinais de risco do módulo (ver [Indicadores](#indicadores)) — ex.: `criminalRisk`, `creditRisk`, `bankruptcy`. | ### Item de processo {#item-de-processo} Mesma forma em L1 e L2, PF e PJ. | Campo | Tipo | Descrição | | ------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `number` | string | Número CNJ do processo. | | `name` / `nationalId` | string | Nome e documento da parte à qual este item pertence. | | `type` | string | Tipo processual (rótulo do provedor). | | `mainSubject` | string | Assunto principal. | | `cnjProcedureType` / `cnjSubject` | string | Tipo/assunto normalizados na taxonomia CNJ. | | `court` | object | Vara/tribunal: `name`, `level`, `type`, `district`, `state`. | | `status` | string | Situação bruta do provedor. | | `stage` | string | Classificação fechada derivada de `status`: `active` / `suspended` / `terminal` / `unknown` (use este para branch). | | `specificType` | string | Papel específico do titular no processo (ex.: `REU`, `INDICIADO`). | | `polarity` | string | Polo do titular: `ACTIVE` / `PASSIVE`. | | `partType` | string | Categoria da parte: `accused`, `claimant`, `defendant`, etc. | | `relationship` | string | Relação do titular com o processo: `exposure` (réu/acusado — risco), `activity` (autor/exequente), `context` (terceiro/vítima), `neutral` (advogado/juiz). | | `debitAmount` | number | Valor da dívida/causa quando disponível (`-1` = não informado). | | `parties` | array | Partes do processo: `{nationalId, name, polarity, partType, specificType, isInference}`. | | `entityType` | string | `PERSON` / `COMPANY`. | | `level` | string | `L1` (entidade verificada) ou `L2` (co-réu). | | `ruleApplied` | bool | `true` se este processo contribuiu com pontuação positiva no score. | | `ruleSeverity` | string | Criticidade: `none`, `very_low`, `low`, `medium`, `high`, `critical`. | | `indicators` | array | Indicadores da taxonomia acionados por este processo: `{name, dimension, involvement}`. | | `relatedLawsuits` | array | Números CNJ de processos ligados a este (ex.: execução × origem). | | `distributionDate` / `lastUpdateDate` | string | Datas de distribuição e última movimentação. | > Os campos internos `confidence` e `prediction` **não** são retornados no payload. ### Co-réu (L2) {#co-reu-l2} Cada entrada de `defendant.person` / `defendant.company` embrulha os processos de um co-réu: | Campo | Descrição | | --------------------- | ----------------------------------------------------------------------------------------------------- | | `nationalId` / `name` | Documento e nome do co-réu. | | `level` | Sempre `L2`. | | `entityType` | `PERSON` / `COMPANY`. | | `relationship` | Vínculo com o titular: `{type, level}` (ex.: `REU_JUNTO` / `INDIRECT`). | | `lawsuits` | `{items, counters}` — os processos do co-réu, cada um no [item de processo](#item-de-processo) acima. | ## Indicadores Cada módulo expõe um bloco `indicators` com sinais tipados no formato `{ risky: boolean, value: number }` — `risky` marca o sinal como risco e `value` é a contagem/medida associada (ex.: `protests`, `criminalRisk`, `activeOwnership`). São a base determinística do scoring, independente da IA. Para o exemplo completo do corpo, veja a resposta do [`GET /api/v2/verifications/{id}`](/api/decision-engine/getVerification). Para o resumo por IA (quando habilitado), veja [`GET /api/v2/verifications/{id}/ai-summary`](/api/decision-engine/getVerificationAiSummary).