> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Pessoas-chave de empresas: UBOs e administradores

> Associe UBOs, administradores e beneficiários efetivos a uma entidade Business da Didit. Cada um faz KYC como entidade User. KYB em circuito fechado.

Cada entidade Business tem **pessoas-chave**: as pessoas singulares que são legalmente responsáveis pela empresa ou que são beneficiárias efetivas dela. A Didit identifica-as durante o KYB e permite-lhe ligar cada uma a uma entidade User para KYC individual.

## Quem é considerado pessoa-chave

| Função | Descrição |
| - | - |
| **Administrador** | Indicado no registo como administrador da empresa |
| **Titular de cargo** | Secretário, representante ou outro titular de cargo registado |
| **Acionista** | Acionista registado (pessoa coletiva ou singular) |
| **UBO (beneficiário efetivo final)** | Pessoa singular que, em última instância, detém ou controla 10/25/50%+ (limiar configurável) |
| **Signatário autorizado** | Pessoa com poderes para agir em nome da empresa |

Consulte as páginas [Titulares de cargos KYB](https://docs.didit.me/pt/business-verification/officers.md) e [Propriedade](https://docs.didit.me/pt/business-verification/ownership.md) para a taxonomia completa das funções e o cálculo da cadeia de propriedade.

## Como as pessoas-chave são associadas a uma Business

**1. Identificadas a partir do registo**

Durante o KYB, a Didit consulta o registo de empresas e extrai todos os titulares de cargos e acionistas indicados. Cada pessoa passa a ser um **registo de pessoa-chave** associado à sessão de Verificação de empresas (KYB).

**2. Adicionadas pelo utilizador (preenchidas pelo cliente)**

Os fluxos podem incluir um passo «Pessoas-chave» em que o administrador da empresa adiciona pessoas que não constam do registo (por exemplo, UBO identificados por declaração societária).

**3. Agregadas na entidade Business**

A lista de pessoas-chave da entidade Business é a união das partes extraídas do registo e das partes adicionadas pelo utilizador, sem duplicados, com base na identidade.

Cada pessoa-chave tem um campo `source`:

* `REGISTRY` — extraída de um registo oficial.
* `USER` — adicionada pelo administrador da empresa durante o fluxo de KYB.

## Ligar uma pessoa-chave a uma entidade User

Quando é necessário KYC para uma pessoa-chave (normalmente UBO e administradores), a parte pode ser ligada a uma entidade User:

```mermaid theme={null}
flowchart LR
    B[Business: biz-acme]
    P1[Key Person: Jane Doe, Director]
    P2[Key Person: John Smith, UBO 40%]
    U1[User: user-jane]
    U2[User: user-john]
    P1 --> B
    P2 --> B
    P1 -.linked.-> U1
    P2 -.linked.-> U2
```

A ligação é criada quando:

* É executada uma sessão de Verificação de utilizadores (KYC) para a parte, usando o mesmo `vendor_data` da entidade User.
* Um analista associa manualmente uma parte da empresa a um User existente.

Depois de ligado, o estado KYC do User é propagado para a vista de pessoas-chave na entidade Business.

## Consultar pessoas-chave

Na página de detalhe da Business na consola, o separador **Pessoas-chave** mostra:

* O nome, a função, a percentagem de propriedade e a origem de cada parte (registo ou adicionada pelo utilizador)
* O estado de KYC dos Users ligados
* O estado da triagem AML de cada pessoa
* Os documentos associados (documento de identificação do administrador, declaração de UBO)

Programaticamente, as pessoas-chave aparecem no array `key_people_checks[]` da decisão da sessão de Verificação de empresas (KYB), com os resultados divididos em dois grupos:

```json theme={null}
"key_people_checks": [
  {
    "status": "Approved",
    "node_id": "feature_kyb_key_people",
    "registry": {
      "officers": [
        { "uuid": "...", "name": "Jane Doe", "role": "director", "kyc_status": "Approved", "kyc_session_url": "..." }
      ],
      "beneficial_owners": [
        { "uuid": "...", "name": "John Smith", "roles": ["ubo"], "ownership_min_shares": 40, "kyc_status": "Pending" }
      ]
    },
    "submitted": {
      "parties": [
        { "uuid": "...", "entity_type": "person", "name": "Alice Chen", "role": "ubo", "ownership_percent": 35.0, "source": "USER", "requires_verification": true, "kyc_session_status": "Not Started", "kyc_session_url": "..." }
      ]
    },
    "ubo_kyc_summary": { "total": 2, "approved": 1, "flagged": 0, "pending": 1 }
  }
]
```

* **`registry.officers` / `registry.beneficial_owners`** — partes identificadas através da verificação no registo.
* **`submitted.parties`** — partes adicionadas pelo administrador da empresa durante o fluxo Pessoas-chave (`source: USER`).
* **`ubo_kyc_summary`** — progresso agregado do KYC dos UBO.

Os arrays planos legados `officers[]` e `beneficial_owners[]` mantêm-se na resposta por compatibilidade com versões anteriores, por mais uma versão. As novas integrações devem usar a estrutura de dois grupos indicada acima. Consulte o [esquema de resposta KYB](https://docs.didit.me/pt/business-verification/response-schema.md#key_people_checks) completo para ver todos os campos.

## Acionistas que são empresas

Quando um acionista é ele próprio uma empresa (e não uma pessoa), a Didit explora recursivamente a cadeia de propriedade para identificar os beneficiários efetivos finais. As entidades empresariais podem, opcionalmente, desencadear sessões filhas de Verificação de empresas (KYB).

Consulte [Estrutura de propriedade](https://docs.didit.me/pt/business-verification/ownership.md) para ver um exemplo prático de cadeias de propriedade com várias camadas.

## Webhooks de pessoas-chave

As alterações às pessoas-chave são comunicadas através dos eventos da sessão principal:

* `data.updated` (com `session_kind: "business"`) — os dados da sessão, incluindo as pessoas-chave, foram atualizados.
* `status.updated` (com `session_kind: "business"`) — o estado da sessão mudou em consequência.

Consulte os [webhooks KYB](https://docs.didit.me/pt/business-verification/webhooks.md) para ver os payloads.

## Próximos passos

> [card] [Titulares de cargos](https://docs.didit.me/pt/business-verification/officers.md)
>
> Identificação de administradores e taxonomia de funções.

> [card] [Propriedade](https://docs.didit.me/pt/business-verification/ownership.md)
>
> UBO, acionistas que são empresas e cálculo da cadeia.

> [card] [Fluxo Pessoas-chave](https://docs.didit.me/pt/business-verification/key-people.md)
>
> O passo KYB que recolhe as pessoas-chave.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.