# Screening do quadro societário

<https://unifokal.com/docs/modulos/screening-socios>

## Screening do quadro societário

Quando o flow tem um módulo de **quadro societário** (`cnpj_socios`, `cnpj_participacoes` ou `cnpj_receita`), cada sócio que veio na consulta é conferido contra as **mesmas listas** do módulo `pep_sancoes`. Não é um módulo novo, não entra no flow e **não custa nada a mais**: os sócios já vinham dentro da consulta que você já paga, e o cruzamento roda na nossa base. O resultado sai no `partner_screening`, dentro do `data` do próprio módulo que trouxe o quadro, ao lado de `company`.

! **Isto é um nível do quadro, não beneficiário final.** A consulta devolve os sócios **diretos** do CNPJ apresentado. Se um deles for pessoa jurídica, este enriquecimento **não sobe a cadeia** para achar quem está atrás dela: aquele ramo fica em aberto, e nós dizemos isso na resposta em vez de deixar parecer concluído. Quem sobe é um **módulo próprio**, a [Cadeia societária](https://unifokal.com/docs/modulos/ubo-profundo#modulo-ubo-profundo) (`ubo_profundo`), que percorre nível a nível até as pessoas naturais e é cobrado por empresa subida, com teto definido por você.

**Cobertura deste enriquecimento**, e nada além dela: **um nível** do quadro societário, com o sócio conferido por **documento** (CPF ou CNPJ, inclusive o CPF mascarado que a Receita publica) e por **nome**. **Cadeia de vários níveis e participação indireta** são o produto do módulo [Cadeia societária](https://unifokal.com/docs/modulos/ubo-profundo#modulo-ubo-profundo), que você liga no flow quando precisa deles. Continuam **fora** de qualquer um dos dois, e não os anunciamos: controle por acordo de acionistas, sócio no exterior que não publica CNPJ e pessoa que controla sem constar do quadro. O **percentual** de participação só existe quando o flow comprou `cnpj_participacoes`: sem ele, nenhuma regra de 25% pode ser calculada, e o campo sai `null` em vez de zero. Acima de **50 sócios** o excedente sai declarado em `partners_truncated`, nunca em silêncio.

O bloco `ubo_coverage` existe para essa honestidade ser **legível por código**, e não só por quem lê esta página: `chain_complete` só é `true` quando **todo** sócio do quadro é pessoa natural identificada, e `unresolved_legal_entities` conta os ramos que ficaram em aberto. Se o seu processo exige beneficiário final, é esse par que diz quando a análise humana ainda precisa continuar.

! **Nenhum sócio reprova a sua verificação.** O quadro é **evidência**: o único efeito possível na decisão é levar de `approved` para `review`, e só no caso de **sanção forte casada por documento**. Semelhança de **nome** nunca move a decisão: o quadro societário não publica data de nascimento, então o desempate que existe para o titular não existe para o sócio, e homônimo é o caso comum. Nunca `denied` automático.

Se uma lista nossa estiver **vencida**, o bloco sai `unavailable` com `dataset_stale` e **cada sócio marcado como indeterminado**: nós não afirmamos "nada consta" sobre um quadro que não conseguimos conferir, e esse caso **não muda a decisão**. O mesmo bloco, com os mesmos sócios indeterminados, sai com `no_coverage` quando nenhuma lista do módulo está disponível e com `critical_source_disabled` quando uma lista que a resposta não pode dispensar está fora do ar. São três motivos para a mesma regra: um veredito sobre o quadro só vale se alguma lista tiver sido de fato consultada. E quando uma lista específica não entrou na consulta, ela aparece no `aggregates.by_list` de **cada sócio** com `null` em vez de sumir do objeto, exatamente como no bloco do titular: "não foi olhada" nunca se parece com "olhada e sem resultado" no seu código. O mesmo vale para sócio sem nome e sem documento na fonte. O **documento do sócio não viaja** dentro de `partner_screening`: ele já está em `company.socios`, no mesmo check, sob a mesma cifra e o mesmo direito de exclusão.

```
// cnpj_socios: quadro conferido, um sócio sancionado (evidência; só vai a review se você ligar)
{ "module": "cnpj_socios", "passed": true, "outcome": "approved", "score": 95,
  "data": {
    "company": { "cnpj": "46157128000164", "razao_social": "EXEMPLO LTDA", "socios": [ /* ... */ ] },
    "partner_screening": {
      "status": "flagged", "reason": "partner_sanction_document", "review": true,
      "partners_total": 2, "partners_screened": 2, "partners_flagged": 1,
      "partners_indeterminate": 0, "partners_truncated": false,
      "partners": [
        { "name": "JOSE CARLOS DA SILVA", "qualification": "Sócio-Administrador",
          "entity_type": "person", "percentual": null, "matchable": true,
          "status": "flagged", "reason": "sanction_document", "matched_by": "document",
          "hits": [ { "source": "cgu_ceis", "list": "CEIS", "matched_by": "document",
                      "strong": true, "similarity": 1, "entry_ref": "cgu_ceis:1182" } ] },
        { "name": "SOCIO LIMPO", "qualification": "Sócio", "entity_type": "person",
          "status": "clear", "reason": "clean", "matched_by": "none", "hits": [] }
      ],
      // o que dá e o que NÃO dá para afirmar sobre beneficiario final
      "ubo_coverage": { "level": 1, "chain_complete": true, "percentual_available": false,
                        "unresolved_legal_entities": 0, "presumption_threshold_pct": 25,
                        "candidates_over_threshold": null },
      "model_version": "partner-screening-v1" } } }

// cnpj_socios: sócio pessoa jurídica no quadro (a cadeia NÃO se fecha, e a resposta diz isso)
{ "module": "cnpj_socios", "passed": true, "outcome": "approved", "score": 95,
  "data": { "partner_screening": {
    "status": "clear", "reason": "clean", "review": false,
    "ubo_coverage": { "level": 1, "chain_complete": false, "unresolved_legal_entities": 1 } } } }

// cnpj_socios: lista nossa vencida (indeterminado explícito, nunca "limpo")
{ "module": "cnpj_socios", "passed": true, "outcome": "approved", "score": 95,
  "data": { "partner_screening": {
    "status": "unavailable", "reason": "dataset_stale", "review": false,
    "stale_sources": ["cgu_ceis"],
    "partners": [ { "name": "JOSE CARLOS DA SILVA", "status": "indeterminate",
                    "reason": "dataset_stale", "hits": [] } ] } } }

// cnpj_socios: nenhuma lista do modulo disponivel (mesmo bloco, outro motivo).
// disabled_sources traz o catalogo INTEIRO do modulo neste caso; o exemplo mostra so duas entradas.
{ "module": "cnpj_socios", "passed": true, "outcome": "approved", "score": 95,
  "data": { "partner_screening": {
    "status": "unavailable", "reason": "no_coverage", "review": false,
    "disabled_sources": ["cgu_ceis", "cgu_pep"],
    "partners": [ { "name": "JOSE CARLOS DA SILVA", "status": "indeterminate",
                    "reason": "no_coverage", "hits": [] } ] } } }
```