# Cadeia societária até o beneficiário final

<https://unifokal.com/docs/modulos/ubo-profundo>

## Cadeia societária até o beneficiário final

O módulo `ubo_profundo` é o que **sobe a cadeia** quando um sócio da empresa é outra empresa: nível a nível, até as pessoas naturais que de fato a controlam, com o **percentual acumulado** de cada uma pelo caminho. É a pergunta da **IN RFB 2.119/2022** e da **Circular BCB 3.978/2020**: quem detém 25% do capital, direta ou indiretamente, e quem exerce o controle. Ele exige a **Participação Societária** no mesmo flow, que é de onde vem o percentual de cada sócio.

! **Cobrança por empresa efetivamente subida, com teto que é seu.** O preço unitário multiplica o número de empresas que precisaram ser consultadas, até o teto que você define no flow (o custo máximo aparece na tela antes de salvar, e nunca é ultrapassado). Empresa sem sócio pessoa jurídica não sobe nada e não custa nada, e empresa que a fonte não conseguiu responder também não entra na conta. Por sessão, a chave `policy.ubo_max_paid_nodes` só **aperta** esse teto: pedir mais que o do flow é `422 policy_ubo_cap_above_flow`.

```
// check_details do ubo_profundo: a árvore, e os quatro campos de dinheiro
{ "module": "ubo_profundo", "passed": true, "outcome": "approved", "score": 80,
  "data": { "ubo_tree": { "status": "complete", "chain_complete": true,
                          "ubos": [ { "name": "…", "document": "***.456.789-**",
                                      "effective_percent": 51.0, "path": ["…", "…"] } ],
                          "candidates_over_threshold": 1,
                          "cycles": [], "reason": null },
            "nodes_charged": 2, "unit_cents": 1390, "charged_cents": 2780, "cap": 3 } }

// cadeia que NÃO fechou: "parcial" é dito como parcial, nunca como "não há beneficiário final"
{ "module": "ubo_profundo", "passed": null, "outcome": "pending", "score": 0,
  "data": { "ubo_tree": { "status": "partial", "chain_complete": false, "ubos": [],
                          "candidates_over_threshold": null,
                          "reason": "ubo_node_budget_exhausted" },
            "nodes_charged": 3, "unit_cents": 1390, "charged_cents": 4170, "cap": 3 } }
```

Os campos de dinheiro não são decoração: o motivo `ubo_node_budget_exhausted` (**o seu teto mordeu**, e você sabe exatamente quanto custaria subir mais) e o motivo `ubo_source_unavailable` (**a fonte caiu**, não cobra, tente de novo) leriam igual sem `cap` e `nodes_charged` ao lado. Quando a cadeia não fecha, a resposta **diz por quê**: teto atingido, ciclo societário, sócia estrangeira sem CNPJ publicado ou fonte fora do ar. `ubos: []` com `status: "partial"` lê-se **não consegui subir**, jamais **não há beneficiário final**, e `candidates_over_threshold: null` (nunca `0` por omissão) é a outra metade da mesma honestidade. O módulo **informa e não reprova ninguém**: estrutura societária opaca é um fato sobre o registro público, não uma acusação contra quem está se verificando.