> ## 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.

# API de pessoas-chave KYB: UBOs e diretores

> A Didit verifica UBOs, acionistas e diretores em um só fluxo KYB, com sessões KYC vinculadas. A partir de $2.00 por verificação, sem contrato.

**Pessoas-chave** é o modelo unificado da Didit para todas as pessoas físicas e jurídicas vinculada à empresa que você está verificando: UBOs, acionistas (pessoas físicas e jurídicas), diretores, representantes e outras funções de administração. Um único fluxo de Pessoas-chave cobre todos eles, com encaminhamento das verificações de acordo com a função e comparação completa, lado a lado, entre as partes provenientes do registro de empresas e as enviadas pelo usuário.

> [!NOTE]
>
> Para a visão de pessoas-chave da empresa, isto é, como administradores e UBOs são consolidados entre sessões, consulte [Empresas → Pessoas-chave](https://docs.didit.me/pt-br/entities/businesses/key-people.md).

## Como funciona

**1. Pré-preenchimento pelo registro (opcional)**

Se o fluxo de verificação (workflow) habilitar o pré-preenchimento pelo registro, a tela de Pessoas-chave já vem preenchida com os UBOs, acionistas e administradores disponíveis extraídos da verificação de registro.
O usuário final pode editar, adicionar ou remover partes antes de enviar, mesmo quando as informações de propriedade ainda estiverem pendentes.
Os administradores já recebidos continuam disponíveis enquanto o relatório de propriedade é coletado.
Antes do envio, os resultados que chegam depois preenchem os campos não alterados e adicionam as pessoas que faltam, sem substituir edições nem restaurar partes removidas.
Um editor aberto permanece inalterado; o pré-preenchimento adicional é aplicado depois que o solicitante o fecha.
Com o pré-preenchimento pelo registro desativado, os próprios solicitantes informam as pessoas, e os resultados que chegam depois não preenchem este formulário.
Os dados do registro que chegam após o envio continuam fazendo parte das evidências do registro, mas não alteram a lista de pessoas enviada nem criam automaticamente sessões de verificação filhas adicionais.

**2. Envio pelo fluxo hospedado**

O usuário final envia a lista final de pessoas-chave pelo fluxo de verificação hospedado. Por padrão, você não chama esta etapa: ela acontece dentro do fluxo de KYB cuja URL você forneceu por meio de [Create Session](https://docs.didit.me/pt-br/sessions-api/create-session.md).
Se preferir manter seu próprio front-end, use os endpoints de [rascunho de parte](https://docs.didit.me/pt-br/sessions-api/kyb-create-party-draft.md) e de [envio de partes](https://docs.didit.me/pt-br/sessions-api/kyb-submit-parties.md).

**3. Roteamento de verificação conforme a função**

Para cada parte enviada, a Didit verifica as configurações de verificação definidas para a função:

* Aplica o limiar de propriedade do fluxo: UBOs e acionistas abaixo do percentual configurado não exigem verificação individual.
* Respeita a opção "pular verificação" marcada pelo usuário final, se a função permitir pular.
* Cria uma sessão filha de Verificação de Usuário (KYC) para as partes que são pessoas físicas e exigem KYC.
* Cria uma subsessão filha de KYB para UBOs corporativos quando o KYB aninhado está habilitado no fluxo.

**4. Progressão de status**

O status do recurso Pessoas-chave passa a ser `Awaiting User` enquanto qualquer sessão filha obrigatória ainda estiver em andamento. Quando todas as sessões filhas terminam, o status passa a ser `Approved`, `Declined` ou `In Review` com base nos resultados.

## Funções coletadas

As pessoas-chave podem ter uma ou mais das funções a seguir; uma mesma pessoa pode ter várias ao mesmo tempo (por exemplo, diretor **e** acionista). A taxonomia completa:

| Categoria | Funções |
| - | - |
| **Propriedade** | `ubo`, `shareholder`, `beneficiary`, `settlor`, `protector`, `investor` |
| **Governança / representação** | `director`, `non_executive_director`, `chairman`, `secretary`, `representative`, `authorized_signatory`, `trustee`, `company_officer`, `founder`, `legal_advisor`, `other` |

Cada função pode ser configurada individualmente no fluxo: habilitada ou desabilitada, obrigatória ou opcional para KYC, mapeada para um fluxo de KYC específico e, opcionalmente, dispensável. Consulte [Propriedade](https://docs.didit.me/pt-br/business-verification/ownership.md) para ver os detalhes do encaminhamento da verificação.

## Dados coletados por pessoa-chave

O fluxo hospedado solicita um conjunto padrão de campos e campos personalizados adicionais configurados no fluxo. Consulte [Propriedade → Campos coletados](https://docs.didit.me/pt-br/business-verification/ownership.md#dados-coletados-para-cada-pessoa-chave) para ver a lista completa.

## Confirmação do registro

Antes da etapa de pessoas-chave, o usuário final revisa os dados da empresa extraídos da consulta ao registro e, se quiser, edita qualquer campo. Em seguida, o fluxo hospedado armazena:

* O **detalhe do registro** que a Didit normalizou a partir da consulta ao registro (`registry_data`).
* Os **dados confirmados pelo usuário** (`user_provided_data`), com um carimbo de data e hora que indica quando o usuário confirmou os dados.
* Uma visão canônica consolidada dos campos de nível superior da empresa: os dados confirmados pelo usuário, quando existem, ou, caso contrário, os dados do registro.

Consulte [Dados da empresa → Dados do registro vs. dados fornecidos pelo usuário](https://docs.didit.me/pt-br/business-verification/company-data.md#dados-do-registro-vs-dados-fornecidos-pelo-usuário) para ver o modelo completo.

## Formato na resposta de decisão

Após o envio, as pessoas-chave coletadas aparecem na decisão de KYB em `key_people_checks[]`, divididas em dois grupos: **registro de empresas** (o que o provedor informou) e **enviadas** (o que o administrador da empresa confirmou durante o fluxo). Há também um `ubo_kyc_summary` que consolida o progresso do KYC dos UBOs. Consulte a [referência completa de key\_people\_checks](https://docs.didit.me/pt-br/business-verification/response-schema.md#key_people_checks).

## Comportamento de reenvio

* **Pessoas-chave** e **Verificação de Registro** não podem ser reenviadas diretamente. Para reverificar uma pessoa específica, reenvie a sessão KYC filha individual dela.
* Quando uma sessão KYC filha é reenviada, o status do recurso pai Pessoas-chave volta automaticamente para `Awaiting User`.
* Quando a sessão filha reenviada termina, o recurso pai agrega novamente os resultados com base nos status de todas as sessões filhas.
* Uma sessão filha que foi excluída, ou que expirou antes de a pessoa iniciá-la, não pode ser reenviada: [regenere a parte](https://docs.didit.me/pt-br/sessions-api/regenerate-kyb-party.md) para emitir um novo link para a mesma parte.

## Por quanto tempo o link de verificação de uma pessoa-chave é válido

A sessão de KYC filha de uma pessoa-chave segue o tempo de expiração de sessão do fluxo de verificação (workflow) de KYC configurado para a função dela, e não o do fluxo de KYB. Se você associar uma função a um fluxo de KYC que permite quatro semanas, o link dessa pessoa continua utilizável por quatro semanas, mesmo quando a sessão da empresa estiver configurada para expirar antes.

O valor é uma configuração por fluxo, de 1 hora a 4 semanas (`session_expiration_time`, em segundos), em *Workflows → \[fluxo de KYC] → Settings*.

A expiração muda o que você pode fazer com a pessoa. Um link que expirou antes de a pessoa começar, assim como um cuja sessão foi excluída, pode ser emitido novamente com [Regenerar sessão de KYC de pessoas-chave](https://docs.didit.me/pt-br/sessions-api/regenerate-kyb-party.md). Sessões excluídas são elegíveis mesmo que a pessoa já tenha iniciado ou concluído a verificação. Sessões importadas não são elegíveis em caso de expiração; elas precisam ter sido excluídas. Uma sessão que não foi excluída e que a pessoa já tinha iniciado não é elegível em caso de expiração.

## Opções de configuração

Todo o comportamento de Key People é configurado por fluxo no Business Console:

| Configuração | O que controla |
| - | - |
| **Preenchimento a partir do registro** | Preenche previamente o formulário de Key People com dados do registro |
| **Campos extras — pessoas** | Campos personalizados a coletar para cada parte que seja pessoa física |
| **Campos extras — empresas** | Campos personalizados a coletar para cada parte que seja pessoa jurídica |
| **Limiar de propriedade de UBO** | Percentual mínimo de propriedade para classificar alguém como UBO |
| **Limiar de propriedade de acionista** | Percentual mínimo de propriedade para classificar alguém como acionista |
| **Configurações por função** | Para cada função: ativada/desativada, exigir KYC, fluxo de KYC a usar, pode ser ignorada |
| **KYB aninhado para UBO corporativo** | Quando ativado, UBOs que são pessoas jurídicas iniciam suas próprias sessões de KYB filhas |
| **Reutilizar indivíduos verificados** | Veja [Reutilização de indivíduos verificados entre verificações de KYB](#reutilização-de-indivíduos-verificados-entre-verificações-de-kyb) abaixo |
| **Notificar partes por e-mail** | Envia automaticamente por e-mail a cada pessoa-chave o seu link de verificação |

Configure em *Workflows → \[fluxo de KYB] → Key People* no console.

## Reutilização de indivíduos verificados entre verificações de KYB

Quando **Reutilizar indivíduos verificados** está ativado em um fluxo (o padrão), uma pessoa-chave não precisa refazer o KYC toda vez que aparece em uma nova verificação de KYB. A Didit procura um KYC aprovado existente de uma verificação de KYB anterior e o vincula à nova parte, em vez de criar uma nova sessão de KYC filha.

> [!NOTE]
>
> Este é um mecanismo diferente do [KYC reutilizável](https://docs.didit.me/pt-br/core-technology/reusable-kyc/overview.md), que permite a um *usuário final* levar voluntariamente uma sessão concluída para diferentes aplicações integradas à Didit por meio de um token de compartilhamento/importação. A configuração de reutilização de KYB desta página é automática, configurada no fluxo e restrita às pessoas-chave dentro de uma única aplicação - sem token de compartilhamento e sem nenhuma ação do usuário final.

**Correspondência.** Uma possível correspondência é encontrada comparando o nome completo da pessoa informada (sem diferenciar maiúsculas de minúsculas e sem espaços nas extremidades) com as pessoas-chave das outras verificações de KYB da aplicação. Não há nenhum sinal adicional de correspondência - a coincidência de número de documento, e-mail ou telefone não é exigida nem verificada. Um nome digitado com grafia diferente, com um nome do meio ou com uma transliteração não terá correspondência e, em casos raros, duas pessoas diferentes com o mesmo nome podem ser consideradas correspondentes; revise os resultados de Key People levando isso em conta.

**Escopo.** A correspondência considera todas as outras verificações de KYB que pertencem à *mesma aplicação*, e não apenas a verificação de KYB atual, nem outras aplicações da sua organização. Uma pessoa verificada como UBO na Empresa A pode ter correspondência quando aparecer depois como diretora na Empresa B, desde que as duas verificações sejam executadas na mesma aplicação.

**Status elegíveis.** Somente o KYC **Aprovado** mais recente de uma parte é elegível para reutilização. Um KYC **Recusado** para esse nome bloqueia totalmente a reutilização - a parte é sinalizada e um novo KYC é solicitado, em vez de recorrer ao KYC recusado. Um KYC que ainda está **Em Revisão** nunca é considerado candidato.

**Retenção.** A correspondência considera apenas sessões de KYC criadas no último ano, aproximadamente e que não foram excluídas. Se a única sessão correspondente estiver fora dessa janela, ou se a pessoa ou a organização a tiver excluído, a verificação não encontra nenhuma correspondência elegível e solicita silenciosamente um novo KYC - ela nunca falha nem bloqueia o envio de Key People.

**Faturamento.** Um KYC reutilizado não é cobrado novamente. Vincular uma sessão já aprovada à nova parte não gera nenhuma cobrança adicional; você é cobrado apenas uma vez, pelo KYC original.

```txt Example theme={null}
Company A: Jane Doe submitted as UBO, KYC approved.
Company B (same application): Jane Doe submitted as a director.
"Reuse verified individuals" is enabled, so Company B's Key People
check links Jane's existing approved KYC instead of requesting a
new one - free, and instantly Approved for that party.
```

## Próximos passos

> [card] [Propriedade](https://docs.didit.me/pt-br/business-verification/ownership.md)
>
> Campos coletados, dados personalizados e conciliação entre registro e dados enviados.

> [card] [Administradores e representantes](https://docs.didit.me/pt-br/business-verification/officers.md)
>
> Funções de governança dentro do modelo de pessoas-chave.

> [card] [Esquema de resposta](https://docs.didit.me/pt-br/business-verification/response-schema.md#key_people_checks)
>
> Referência campo a campo de `key_people_checks[]`.


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