Como interpretar a resposta do Screening

Manual para uma aplicação cliente interpretar a resposta do endpoint público POST /v1/screening, inclusive quando a consulta avançada expande a rede societária por meio de ownership_network.

Textos apresentados ao usuário podem ser localizados pela camada cliente. A documentação interativa (/docs) é a referência de tipos e campos; este manual explica a semântica e a ordem de leitura.

A recomendação da API apoia a decisão de compliance. Ela não substitui a política, as aprovações ou a análise humana exigida pelo cliente.

Ordem segura de leitura

Uma resposta longa não deve ser lida como uma lista única de ocorrências. O consumidor deve seguir esta sequência:

1. Confirmar se a resposta é conclusiva (status).
2. Ler a decisão sobre o sujeito consultado diretamente.
3. Avaliar as ocorrências e a cobertura das fontes.
4. Avaliar separadamente a rede societária, quando solicitada.
5. Usar o dossiê e a cobrança como evidência e rastreabilidade.

1. A resposta é conclusiva?

{
  "status": "COMPLETE",
  "billable": true,
  "warnings": [],
  "notices": []
}

Exemplo de resposta que exige repetição ou revisão, e não aprovação:

{
  "status": "PARTIAL",
  "billable": false,
  "notices": [
    {
      "code": "PARTIAL_SOURCE_FAILURE",
      "severity": "WARNING",
      "message": "Partial screening: at least one selected live source was unavailable. The result is not conclusive and was not charged. Run the screening again."
    }
  ]
}

2. Decisão sobre o sujeito consultado diretamente

{
  "risk_level": "HIGH",
  "identity_class": "TRUE_MATCH",
  "recommendation": "REJECT",
  "summary": "One or more high-risk matches have confirmed identity. Blocking is recommended subject to your compliance policy."
}

Esses quatro campos descrevem somente a pessoa ou empresa enviada no request. Eles não devem ser assumidos como um resumo automático da rede QSA.

Classes de identidade

Níveis de risco

Uma política típica de integração é:

COMPLETE + CLEAR + NO_MATCH             -> seguir, respeitando o escopo consultado
COMPLETE + MEDIUM ou POTENTIAL_MATCH    -> revisão humana
COMPLETE + HIGH + TRUE_MATCH            -> bloquear ou escalar conforme a política
PARTIAL ou ERROR                        -> não aprovar automaticamente

PEP é um caso próprio: requires_edd: true exige diligência reforçada, mas a condição de PEP, isoladamente, não é motivo de bloqueio automático.

3. Ocorrências diretas: hits

{
  "total_hits": 2,
  "actionable_hits_count": 2,
  "informational_hits_count": 3,
  "returned_hits_count": 2,
  "hits_truncated": false,
  "hits": [
    {
      "source": "OFAC_SDN",
      "category": "Financial Sanction",
      "name_similarity": 0.98,
      "identity_confidence": 1.0,
      "document_evidence": "EXACT_MATCH",
      "identity_class": "TRUE_MATCH",
      "risk_level": "HIGH",
      "requires_edd": true,
      "downgraded": false
    }
  ]
}

Nunca tome uma decisão somente por name_similarity. Use identity_class, risk_level, document_evidence e o contexto da fonte.

4. Cobertura das fontes: sources_checked

sources_checked é a prova de quais fontes foram efetivamente consultadas e do que ocorreu em cada uma delas.

{
  "sources_checked": {
    "OFAC_SDN": {
      "list_status": "AVAILABLE",
      "query_result": "MATCH",
      "risk_level": "HIGH",
      "hits": 1,
      "confirmed_hits": 1,
      "potential_hits": 0,
      "skip_reason": null
    },
    "PY_DNIT_RUC": {
      "list_status": "NOT_APPLICABLE",
      "query_result": "NOT_QUERIED",
      "hits": 0,
      "skip_reason": "COMPATIBLE_DOCUMENT_REQUIRED"
    }
  }
}

• Uma fonte com NO_MATCH só sustenta uma conclusão se tiver sido realmente consultada.
• skip_reason: COMPATIBLE_DOCUMENT_REQUIRED não é falha: aquela fonte exige documento compatível e não pode ser pesquisada somente pelo nome.
• error preenchido, fonte indisponível ou aviso de escopo parcial impede tratar a resposta como cobertura integral.
• confirmed_hits, potential_hits, weak_hits e best_match_class ajudam a explicar a qualidade das evidências por fonte.

5. Solicitação de QSA

O QSA é um enriquecimento interno retornado pela mesma chamada de Screening. Para solicitá-lo, o consumidor adiciona estes campos ao corpo de POST /v1/screening:

{
  "name": "EMPRESA ALFA LTDA",
  "cnpj": "12345678000190",
  "groups": ["national", "sanctions"],
  "advanced": true,
  "ownership_depth": 3
}

ownership_depth pode ir de 1 a 8 e exige advanced: true mais CPF ou CNPJ. O QSA não é executado em profundidade 0.

6. O que um nível QSA representa

Um nível é uma rodada completa de expansão societária, não uma alternância fixa entre empresas e sócios.

Raiz CPF

PF consultada
└── nível 1: empresas em que a PF aparece como sócia
    └── nível 2: sócios dessas empresas e empresas participadas por elas
        └── nível 3: expansão das entidades novas do nível 2

Raiz CNPJ

Empresa consultada (nível 0)
├── nível 1: seus sócios
├── nível 1: empresas das quais ela também participa
└── nível 2: expansão das novas PFs e PJs do nível 1
    └── nível 3: expansão das entidades novas do nível 2

O nível mede distância na expansão, não risco, participação societária ou controle. Uma entidade de nível 3 pode ser mais grave que uma de nível 1, e vice-versa.

7. Como ler uma resposta em vários níveis

{
  "ownership_network": {
    "status": "FOUND",
    "queried_cnpj_root": "12345678",
    "requested_depth": 3,
    "reached_depth": 3,
    "billable_depth": 3,
    "total_companies": 4,
    "companies": [
      {
        "cnpj_root": "12345678",
        "legal_name": "EMPRESA CONSULTADA LTDA",
        "level": 0,
        "partners": [
          {
            "level": 1,
            "name": "ANA EXEMPLO",
            "party_type": "PF",
            "role": "SOCIO-ADMINISTRADOR"
          }
        ]
      },
      {
        "cnpj_root": "87654321",
        "legal_name": "HOLDING ALFA LTDA",
        "level": 1,
        "originating_partner_name": "EMPRESA CONSULTADA LTDA",
        "screening": {
          "risk_level": "CLEAR",
          "identity_class": "NO_MATCH",
          "recommendation": "APPROVE"
        }
      },
      {
        "cnpj_root": "11223344",
        "legal_name": "BETA PARTICIPACOES LTDA",
        "level": 2,
        "originating_partner_name": "ANA EXEMPLO",
        "screening": {
          "risk_level": "MEDIUM",
          "identity_class": "TRUE_MATCH",
          "recommendation": "REVIEW",
          "actionable_hits_count": 1
        }
      },
      {
        "cnpj_root": "55667788",
        "legal_name": "GAMMA INVESTIMENTOS LTDA",
        "level": 3,
        "originating_partner_name": "BETA PARTICIPACOES LTDA",
        "screening": {
          "risk_level": "HIGH",
          "identity_class": "TRUE_MATCH",
          "recommendation": "REJECT",
          "actionable_hits_count": 1
        }
      }
    ]
  }
}

O cliente deve analisar cada company.screening e cada company.partners[].screening como uma conclusão sobre aquela entidade relacionada.

No exemplo acima, o resultado principal pode continuar CLEAR, mas o cliente deve exibir algo como:

Sujeito principal: sem ocorrência acionável.
Rede societária: risco alto encontrado no nível 3 em GAMMA INVESTIMENTOS LTDA.
Próxima ação: revisão de compliance da rede societária.

Isso preserva a verdade do contrato: risco direto e risco de relacionamento não são a mesma afirmação.

Apresentação recomendada

Agrupar a lista por level é mais seguro que tentar desenhar uma árvore jurídica exata:

Rede societária — 3 de 3 níveis concluídos

Nível 0
• EMPRESA CONSULTADA LTDA

Nível 1 — vínculos diretos
• ANA EXEMPLO — sócia-administradora
• HOLDING ALFA LTDA — sem ocorrência acionável

Nível 2 — vínculos dos relacionados
• BETA PARTICIPAÇÕES LTDA — revisão necessária

Nível 3 — expansão adicional
• GAMMA INVESTIMENTOS LTDA — risco alto confirmado

companies é uma lista plana. originating_partner_name indica por qual sócio a empresa foi encontrada, mas o contrato não inclui um identificador de empresa-pai ou de aresta. Assim, nomes iguais podem tornar uma árvore gráfica ambígua. A interface deve preferir a formulação "encontrada no nível X via Y".

8. Completude, limites e custo do QSA

{
  "ownership_network": {
    "requested_depth": 3,
    "reached_depth": 2,
    "warnings": ["The ownership entity limit was reached."],
    "derived_screening": {
      "entities_processed": 100,
      "unique_entities": 98,
      "relationships_found": 156,
      "entity_limit": 100,
      "interpol_excluded": true
    },
    "billing": {
      "base_groups": ["national", "sanctions"],
      "base_group_cost": 2,
      "billable_depth": 2,
      "ownership_tokens": 4,
      "interpol_excluded": true
    }
  }
}

Quando o QSA é executado, a profundidade cobrável mínima é 1, mesmo sem vínculos encontrados. O custo de expansão é baseado no custo dos grupos de fontes e na profundidade efetivamente cobrável. Se o QSA estiver indisponível, a consulta principal pode continuar; nesse caso, trate o bloco societário como indisponível e siga os avisos e a cobrança devolvidos.

9. Dossiê e trilha de auditoria

dossier organiza as evidências do sujeito principal para auditoria:

{
  "dossier": {
    "audit_trail": {
      "api_version": "v1",
      "timestamp_utc": "2026-08-04T12:15:18Z",
      "groups_checked": ["national", "sanctions"],
      "tokens_charged": 6
    },
    "decision": {
      "risk_level": "MEDIUM",
      "identity_class": "POTENTIAL_MATCH",
      "recommendation": "REVIEW"
    },
    "regulatory_taxonomy": {
      "by_category": {
        "Politically Exposed Person (PEP)": 1
      },
      "risk_by_category": {
        "Politically Exposed Person (PEP)": "MEDIUM"
      }
    },
    "proof_of_compliance": {
      "status": "RECORDED",
      "ledger_ref": "SCR-20260804-ABC123",
      "hash": "..."
    }
  }
}

O dossiê não deve ser usado para recalcular a decisão: ele é uma apresentação auditável de decision, detailed_hits, taxonomia e evidência de cobrança.

10. Resultado resumido para a interface do cliente

Uma aplicação pode exibir um resumo próprio, desde que preserve a resposta original para auditoria:

{
  "screening_completeness": "COMPLETE",
  "direct_subject": {
    "risk": "CLEAR",
    "identity": "NO_MATCH",
    "recommendation": "APPROVE",
    "actionable_hits": 0
  },
  "ownership_network": {
    "status": "FOUND",
    "requested_depth": 3,
    "reached_depth": 3,
    "related_entities_with_actionable_hits": 2,
    "highest_related_risk": "HIGH"
  },
  "next_action": "MANUAL_REVIEW"
}

related_entities_with_actionable_hits, highest_related_risk e next_action são exemplos de campos calculados pela aplicação cliente. Eles não substituem os campos oficiais devolvidos pela API.

11. Checklist de implementação

• Validar status antes de consumir qualquer recomendação.
• Tratar risk_level e identity_class como eixos independentes.
• Exibir notices e registrar a resposta integral.
• Não confundir resultado direto com risco da rede societária.
• Avaliar cada company.screening e partners[].screening do QSA.
• Mostrar requested_depth, reached_depth, avisos e limites da rede.
• Sinalizar que o Interpol é excluído da análise derivada do QSA.
• Usar tokens_charged, token_balance, billing e proof_of_compliance para rastreabilidade.
• Nunca inferir que uma fonte foi consultada apenas porque não há hits; usar sources_checked.