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

# Entità: Utenti e Aziende in Didit

> Utenti e Aziende sono le due entità principali di Didit. Ognuna raccoglie in un unico profilo sessioni KYC, transazioni, documenti, dati biometrici e rischio.

Didit organizza tutto ciò che accade nella tua applicazione attorno a due tipi di entità di prima classe:

| Entità | Rappresenta | Collegata a |
| - | - | - |
| **Utente** | Una persona fisica | Sessioni di Verifica degli utenti (KYC), dati biometrici del volto, transazioni (come richiedente o controparte), blocklist |
| **Azienda** | Un soggetto giuridico (società, S.r.l., ditta individuale, fondo) | Sessioni di Verifica aziendale (KYB), dirigenti, UBO, transazioni (come richiedente o controparte), blocklist |

Ogni sessione di verifica, ogni transazione e ogni voce di blocklist può essere associata a un'entità. Una volta associata, l'entità diventa un profilo duraturo che aggrega cronologia, segnali di rischio e stato di compliance nel tempo.

## Entità e sessione

Un'**entità** e una **sessione** sono cose diverse.

| Concetto | Ambito | Durata | Esempio |
| - | - | - | - |
| **Sessione** | Un singolo evento di verifica | Un singolo flusso (da pochi minuti a diversi giorni, mentre è in revisione) | Un singolo tentativo di KYC |
| **Entità** | Un profilo duraturo | Dura finché l'utente o l'azienda esiste sulla tua piattaforma | Il cliente "Jane Doe" con 3 sessioni di Verifica degli utenti (KYC) nell'arco di 2 anni |

Una singola entità può avere molte sessioni: nuove verifiche, reinvii, controlli aggiuntivi, monitoraggio continuo periodico. L'entità aggrega i risultati.

## Creazione automatica o pre-creazione manuale

Le entità vengono create in uno di tre modi:

**1. Creata automaticamente da una sessione**

Quando crei una sessione con un identificatore `vendor_data` e non esiste un'entità corrispondente, Didit crea automaticamente l'entità. Questo è il percorso più comune.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "workflow_id": "wf_kyc_standard", "vendor_data": "user-42" }'
```

Un'entità Utente per `user-42` viene creata nel momento in cui inizia la sessione.

**2. Pre-creata tramite la Management API**

Crea prima l'entità, poi avvia le sessioni collegate. Utile quando vuoi inserire in anticipo segnali di rischio (stato, tag, metadati personalizzati) prima della prima verifica.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "vendor_data": "user-42", "display_name": "Jane Doe" }'
```

**3. Creata nella console**

Il tuo team di compliance può creare utenti o aziende direttamente dalla Business Console, utile per l'onboarding manuale, le importazioni o i flussi di risoluzione.

## Come le entità collegano tutto

Il campo `vendor_data` è la chiave di collegamento. Quando passi `vendor_data` in una sessione o transazione, Didit lo instrada verso l'entità corrispondente.

```mermaid theme={null}
flowchart LR
    VD["vendor_data:<br/>user-42"] --> U[User entity]
    S1[User Verification (KYC) session #1] --> VD
    S2[User Verification (KYC) session #2] --> VD
    T1[Transaction #1] --> VD
    T2[Transaction #2] --> VD
    F[Face biometric] --> VD
    D[Documents] --> VD
    BL[Blocklist entry] --> VD
```

Scopri di più nella [guida al collegamento tramite `vendor_data`](https://docs.didit.me/it/entities/vendor-data-linking).

## Cosa puoi fare con un'entità

Per ogni entità Utente o Azienda, puoi:

| Operazione | Scopo |
| - | - |
| **Creare / aggiornare** | Impostare o modificare i dati del profilo dell'entità (nome, paese, metadati personalizzati) |
| **Cambiare stato** | Impostare come `ACTIVE`, `FLAGGED` o `BLOCKED`: l'applicazione dei blocchi si propaga alle sessioni e alle transazioni future |
| **Allegare dati biometrici** | Caricare un riferimento del volto per la ricerca 1:N, il rilevamento dei duplicati o l'inserimento in blocklist |
| **Consultare la cronologia KYC/KYB** | Recuperare ogni sessione collegata all'entità, con i risultati per ogni funzionalità |
| **Consultare la cronologia delle transazioni** | Recuperare ogni transazione in cui l'entità è il richiedente o la controparte |
| **Aggiungere a una blocklist** | Bloccare le sessioni o transazioni future che coinvolgono questa entità |
| **Importare / esportare** | Caricare in blocco entità da CSV o esportarle per strumenti di compliance esterni |
| **Eliminare** | Eliminare l'entità (la cronologia viene conservata per l'audit) |

Le guide dettagliate si trovano in [Utenti](https://docs.didit.me/it/entities/users/overview.md) e [Aziende](https://docs.didit.me/it/entities/businesses/overview.md).

## Relazioni tra Utente ↔ Azienda

Un singolo Utente può essere collegato a una o più Aziende. Questo accade in modo naturale durante il KYB:

* Un Utente può essere un **amministratore** di un'Azienda e un **UBO** di un'altra.
* La sessione di Verifica degli utenti (KYC) di un Utente può essere collegata a una sessione di Verifica aziendale (KYB) di un'Azienda tramite il flusso [Persone chiave](https://docs.didit.me/it/business-verification/key-people.md).

Didit conserva queste relazioni: quando esamini un'entità Azienda, puoi vedere ogni Utente collegato, e quando esamini un'entità Utente, puoi vedere ogni Azienda a cui è associato.

## Ciclo di vita e stati

Ogni entità ha uno stato che determina se Didit applica i blocchi alle nuove attività:

| Stato | Effetto |
| - | - |
| `ACTIVE` | Normale: sessioni e transazioni procedono come configurato dai workflow e dalle regole |
| `FLAGGED` | Sessioni e transazioni sono consentite, ma vengono instradate automaticamente alla revisione manuale |
| `BLOCKED` | Sessioni e transazioni vengono rifiutate automaticamente e non è possibile creare nuove sessioni |

Consulta il [ciclo di vita completo dell'entità](https://docs.didit.me/it/entities/lifecycle.md) per le transizioni e gli eventi webhook.

## Prossimi passi

> [card] [Ciclo di vita](https://docs.didit.me/it/entities/lifecycle.md)
>
> Stati, transizioni ed eventi del ciclo di vita per ogni entità.

> [card] [Collegamento vendor\_data](https://docs.didit.me/it/entities/vendor-data-linking.md)
>
> Come `vendor_data` associa sessioni, transazioni ed entità.

> [card] [Utenti](https://docs.didit.me/it/entities/users/overview.md)
>
> Approfondimento sulle entità Utente, le operazioni e i flussi della console.

> [card] [Aziende](https://docs.didit.me/it/entities/businesses/overview.md)
>
> Approfondimento sulle entità Azienda, le operazioni e i flussi della console.

> [card] [Webhook delle entità](https://docs.didit.me/it/entities/webhooks.md)
>
> Eventi in tempo reale per ogni modifica di un'entità.

> [card] [Blocklist](https://docs.didit.me/it/console/blocklist-users.md)
>
> Come le voci di blocklist interagiscono con le entità Utente e Azienda.


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