> ## 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 KYB persone chiave: titolari e amministratori

> Verifica titolari effettivi, azionisti e amministratori con Didit: flusso KYB unico, controlli per ruolo. Da $2.00 per controllo, senza contratti.

**Persone chiave** è il modello unificato di Didit per ogni persona fisica ed entità giuridica collegata all'azienda che stai verificando: titolari effettivi (UBO), azionisti (persone fisiche e giuridiche), amministratori, rappresentanti e altri ruoli di esponenti. Un unico flusso Persone chiave copre tutti questi casi, con instradamento della verifica in base al ruolo e un confronto completo, affiancato, tra i soggetti ricavati dal registro e quelli inseriti dall'utente.

> [!NOTE]
>
> Per la vista delle persone chiave a livello di azienda, con l'aggregazione di esponenti e UBO tra le sessioni, consulta [Aziende → Persone chiave](https://docs.didit.me/it/entities/businesses/key-people.md).

## Come funziona

**1. Precompilazione dal registro (facoltativa)**

Se il workflow abilita la precompilazione dal registro, la schermata Persone Chiave viene precompilata con i titolari effettivi, gli azionisti e gli esponenti disponibili, estratti dal controllo sul registro.
L'utente finale può modificare, aggiungere o rimuovere soggetti prima dell'invio, anche quando le informazioni sull'assetto proprietario sono ancora in attesa.
Gli esponenti già ricevuti restano disponibili mentre viene raccolto il report sulla proprietà.
Prima dell'invio, i risultati arrivati in ritardo compilano i campi non modificati e aggiungono le persone mancanti, senza sostituire le modifiche né ripristinare i soggetti rimossi.
Un editor aperto resta invariato; la precompilazione aggiuntiva viene applicata dopo che il richiedente lo ha chiuso.
Con la precompilazione dal registro disabilitata, i richiedenti inseriscono le persone da soli e i risultati in ritardo non compilano questo modulo.
I dati del registro arrivati dopo l'invio restano parte delle prove del registro, ma non modificano l'elenco delle persone inviate né creano automaticamente sessioni figlie di verifica aggiuntive.

**2. Invio dal flusso di verifica ospitato**

L'utente finale invia l'elenco definitivo delle persone chiave tramite il flusso di verifica ospitato. Per impostazione predefinita non devi eseguire direttamente questo passaggio: avviene all'interno del flusso KYB il cui URL hai ricevuto da [Crea sessione](https://docs.didit.me/it/sessions-api/create-session.md).
Per mantenere il tuo front end, usa gli endpoint [bozza dei soggetti](https://docs.didit.me/it/sessions-api/kyb-create-party-draft.md) e [invio dei soggetti](https://docs.didit.me/it/sessions-api/kyb-submit-parties.md).

**3. Instradamento della verifica in base al ruolo**

Per ogni soggetto inviato, Didit controlla le impostazioni di verifica configurate per il ruolo:

* Applica la soglia dell'assetto proprietario del workflow: UBO e azionisti sotto la percentuale configurata non richiedono la verifica individuale.
* Rispetta il flag "salta la verifica" impostato dall'utente finale, se il ruolo consente di saltarla.
* Avvia una sessione figlia di Verifica degli utenti (KYC) per i soggetti che sono persone fisiche e che richiedono KYC.
* Avvia una sotto-sessione KYB figlia per i titolari effettivi aziendali quando il KYB annidato è abilitato nel workflow.

**4. Progressione dello stato**

Lo stato della funzionalità Persone chiave diventa `Awaiting User` finché una sessione figlia obbligatoria è ancora in corso. Quando tutte le sessioni figlie terminano, lo stato assume il valore `Approved`, `Declined` o `In Review` in base agli esiti.

## Ruoli raccolti

Le persone chiave possono avere uno o più dei seguenti ruoli: una stessa persona può ricoprirne più d'uno contemporaneamente (per esempio amministratore **e** azionista). La tassonomia completa:

| Categoria | Ruoli |
| - | - |
| **Assetto proprietario** | `ubo`, `shareholder`, `beneficiary`, `settlor`, `protector`, `investor` |
| **Governance / rappresentanza** | `director`, `non_executive_director`, `chairman`, `secretary`, `representative`, `authorized_signatory`, `trustee`, `company_officer`, `founder`, `legal_advisor`, `other` |

Ogni ruolo può essere configurato singolarmente nel workflow: abilitato o disabilitato, obbligatorio o facoltativo per il KYC, associato a un workflow KYC specifico e per il quale è possibile saltare la verifica. Consulta [Assetto proprietario](https://docs.didit.me/it/business-verification/ownership.md) per i dettagli sull'instradamento della verifica.

## Dati raccolti per persona chiave

Il flusso ospitato chiede un insieme predefinito di campi e ulteriori campi personalizzati configurati nel workflow. Consulta [Assetto proprietario → Campi raccolti](https://docs.didit.me/it/business-verification/ownership.md#dati-raccolti-per-ogni-persona-chiave) per l'elenco completo.

## Conferma del registro

Prima della fase Persone chiave, l'utente finale controlla i dati dell'azienda estratti dal controllo sul registro e, se lo desidera, modifica qualsiasi campo. Il flusso ospitato memorizza quindi:

* Il **dettaglio del registro** normalizzato da Didit a partire dal controllo sul registro (`registry_data`).
* I **dati confermati dall'utente** (`user_provided_data`) con un'indicazione temporale che indica il momento della conferma.
* Una vista canonica unificata sui campi aziendali di primo livello: quelli confermati dall'utente quando presenti, altrimenti quelli del registro.

Consulta [Dati aziendali → Dati del registro e dati forniti dall'utente](https://docs.didit.me/it/business-verification/company-data.md#dati-del-registro-e-dati-forniti-dall’utente) per il modello completo.

## Struttura nella risposta della decisione

Dopo l'invio, le persone chiave raccolte compaiono nella decisione KYB sotto `key_people_checks[]`, suddivise in due gruppi: **registro** (quanto dichiarato dal provider) e **inviate** (quanto confermato dall'amministratore aziendale tramite il flusso). Inoltre, `ubo_kyc_summary` riassume l'avanzamento del KYC dei titolari effettivi. Consulta il [riferimento completo di key\_people\_checks](https://docs.didit.me/it/business-verification/response-schema.md#key_people_checks).

## Comportamento in caso di reinvio

* **Persone Chiave** e **Controllo Registro** non possono essere reinviati direttamente. Per verificare di nuovo una persona specifica, reinvia la sua sessione KYC figlia.
* Quando una sessione KYC figlia viene reinviata, lo stato della funzionalità Persone chiave padre torna automaticamente a `Awaiting User`.
* Quando la figlia reinviata termina, lo stato della funzionalità padre viene ricalcolato in base agli stati di tutte le sessioni figlie.
* Una sessione figlia eliminata, o scaduta prima che la persona l'avviasse, non può essere reinviata: [rigenera il soggetto](https://docs.didit.me/it/sessions-api/regenerate-kyb-party.md) per emettere un nuovo link sullo stesso soggetto.

## Per quanto tempo resta valido il link di verifica di una persona chiave

La sessione KYC figlia di una persona chiave segue il tempo di scadenza della sessione del workflow KYC configurato per il suo ruolo, non quello del workflow KYB. Se associ un ruolo a un workflow KYC che consente quattro settimane, il link di quella persona resta utilizzabile per quattro settimane, anche quando la sessione aziendale è impostata per scadere prima.

Il valore è un'impostazione per workflow, da 1 ora a 4 settimane (`session_expiration_time`, in secondi), in *Workflows → \[workflow KYC] → Settings*.

La scadenza cambia ciò che puoi fare con il soggetto. Un link scaduto prima che la persona iniziasse, come quello di una sessione eliminata, può essere riemesso con [Regenerate Key People KYC Session](https://docs.didit.me/it/sessions-api/regenerate-kyb-party.md). Le sessioni eliminate sono idonee anche se la persona aveva già iniziato o completato la verifica. Le sessioni importate non sono idonee in base alla scadenza: devono essere state eliminate. Una sessione non eliminata che la persona aveva già iniziato non è idonea per scadenza.

## Opzioni di configurazione

Tutto il comportamento di Key People si configura per workflow dalla Business Console:

| Impostazione | Cosa controlla |
| - | - |
| **Precompilazione dal registro** | Precompila il modulo Key People con i dati del registro |
| **Campi extra — persone** | Campi personalizzati da raccogliere per ogni parte di tipo persona |
| **Campi extra — aziende** | Campi personalizzati da raccogliere per ogni parte di tipo azienda |
| **Soglia di proprietà UBO** | Percentuale minima di proprietà per classificare una persona come UBO |
| **Soglia di proprietà azionaria** | Percentuale minima di proprietà per classificare una persona come azionista |
| **Impostazioni per ruolo** | Per ogni ruolo: abilitato/disabilitato, richiedi KYC, workflow KYC da usare, saltabile |
| **KYB annidato per UBO aziendali** | Se abilitato, gli UBO aziendali avviano una propria sessione KYB figlia |
| **Riutilizza individui verificati** | Vedi [Riutilizzo di individui verificati tra i controlli KYB](#riutilizzo-di-individui-verificati-tra-i-controlli-kyb) più sotto |
| **Notifica le parti via email** | Invia automaticamente a ogni persona chiave via email il suo link di verifica |

Configura in *Workflows → \[workflow KYB] → Key People* nella console.

## Riutilizzo di individui verificati tra i controlli KYB

Quando **Riutilizza individui verificati** è abilitato su un workflow (impostazione predefinita), una persona chiave non deve ripetere la verifica KYC ogni volta che compare in un nuovo controllo KYB. Didit cerca una verifica KYC approvata esistente da un controllo KYB precedente e la collega alla nuova parte, invece di creare una nuova sessione KYC figlia.

> [!NOTE]
>
> Questo è un meccanismo distinto da [KYC riutilizzabile](https://docs.didit.me/it/core-technology/reusable-kyc/overview.md), che consente a un *utente finale* di portare volontariamente una sessione completata tra applicazioni separate integrate con Didit tramite un token di condivisione o importazione. L'impostazione di riutilizzo KYB di questa pagina è automatica, configurata nel workflow e limitata alle persone chiave all'interno di una singola applicazione - nessun token di condivisione e nessuna azione da parte dell'utente finale.

**Corrispondenza.** Un candidato viene trovato confrontando il nome completo fornito per la persona (senza distinzione tra maiuscole e minuscole, senza spazi iniziali e finali) con le persone chiave degli altri controlli KYB dell'applicazione. Non esistono altri segnali di corrispondenza: non è richiesta né verificata una corrispondenza di numero di documento, email o telefono. Un nome scritto con un'ortografia diversa, un secondo nome o una traslitterazione non corrisponderanno e, in rari casi, due persone diverse con lo stesso nome potrebbero risultare corrispondenti. Tienine conto quando esamini i risultati di Key People.

**Ambito.** La ricerca riguarda tutti gli altri controlli KYB che appartengono alla *stessa applicazione*, non solo il controllo KYB corrente e non le altre applicazioni della tua organizzazione. Una persona verificata come UBO nell'Azienda A può essere associata quando in seguito compare come amministratore nell'Azienda B, purché entrambi i controlli vengano eseguiti nella stessa applicazione.

**Stati idonei.** Solo l'ultimo KYC di una parte con stato **Approvata** è idoneo al riutilizzo. Una verifica KYC con stato **Rifiutata** per quel nome blocca completamente il riutilizzo: la parte viene segnalata e viene richiesto un nuovo KYC, invece di ripiegare su quello rifiutato. Un KYC ancora con stato **In revisione** non viene mai considerato come candidato.

**Conservazione.** La ricerca considera solo le sessioni KYC create negli ultimi circa dodici mesi che non sono state eliminate. Se l'unica sessione corrispondente non rientra in questo intervallo, oppure la persona o l'organizzazione l'ha eliminata, il controllo non trova una corrispondenza idonea e richiede silenziosamente un nuovo KYC: non fallisce né blocca mai l'invio di Key People.

**Fatturazione.** Un KYC riutilizzato non viene fatturato di nuovo. Collegare una sessione già approvata alla nuova parte non comporta alcun costo aggiuntivo: paghi una sola volta, per il KYC originale.

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

## Prossimi passi

> [card] [Assetto proprietario](https://docs.didit.me/it/business-verification/ownership.md)
>
> Campi raccolti, dati personalizzati e riconciliazione tra dati del registro e dati inviati.

> [card] [Cariche e rappresentanti](https://docs.didit.me/it/business-verification/officers.md)
>
> Ruoli di governance all'interno del modello delle persone chiave.

> [card] [Schema della risposta](https://docs.didit.me/it/business-verification/response-schema.md#key_people_checks)
>
> Riferimento campo per campo di `key_people_checks[]`.


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