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

# Ciclo di vita delle entità: stati di utenti e aziende

> Stati e transizioni delle entità Didit Utente e Azienda: creazione, verifica, ACTIVE/FLAGGED/BLOCKED, eliminazione. A consumo per chiamata.

Ogni entità User e Business in Didit attraversa un ciclo di vita prevedibile. Comprendere questo ciclo è fondamentale per progettare i flussi di onboarding, di monitoraggio continuo e di intervento correttivo.

## Diagramma del ciclo di vita

```mermaid theme={null}
stateDiagram-v2
    [*] --> ACTIVE: Created (API, console, or auto from session)
    ACTIVE --> FLAGGED: Rule match / analyst review / suspicious pattern
    FLAGGED --> ACTIVE: Analyst clears / remediation completed
    ACTIVE --> BLOCKED: Manual block / blocklist match
    FLAGGED --> BLOCKED: Investigation concludes blocked
    BLOCKED --> ACTIVE: Manual unblock (analyst only)
```

## Dettaglio degli stati

| Stato | Significato | Applicazione |
| - | - | - |
| `ACTIVE` | Predefinito: l'entità è in regola | Le nuove sessioni e transazioni vengono eseguite tramite i workflow e le regole configurati |
| `FLAGGED` | L'entità ha un problema in sospeso che richiede una revisione | Le nuove sessioni vengono comunque eseguite, ma per impostazione predefinita passano a `IN_REVIEW`; le transazioni possono essere sottoposte automaticamente a un'escalation in base alle regole |
| `BLOCKED` | L'entità è bloccata sulla tua piattaforma | Le nuove sessioni vengono rifiutate automaticamente; le nuove transazioni vengono rifiutate automaticamente; non è possibile creare nuovi link di sessione per questo `vendor_data` |

> [!NOTE]
>
> Modificare lo stato tramite `PATCH /v3/users/{vendor_data}/update-status/` oppure `PATCH /v3/businesses/{vendor_data}/update-status/` emette un webhook (`user.status.updated` / `business.status.updated`), così i sistemi a valle possono reagire in tempo reale.

## Fasi del ciclo di vita

**1. Creazione**

Un'entità viene creata in uno di tre modi:

* **Creata automaticamente** quando avvii una sessione con un nuovo `vendor_data`. L'entità viene creata con stato `ACTIVE`.
* **Pre-creata tramite API** usando `POST /v3/users/create/` oppure `POST /v3/businesses/create/`. Lo stato predefinito è `ACTIVE`.
* **Creata nella console** da un operatore di compliance: lo stato iniziale è `ACTIVE`, salvo diversa indicazione dell'operatore.

Ogni entità riceve un `uuid` generato da Didit e un identificatore `vendor_data` di proprietà del cliente.

**2. Verifica**

Le sessioni vengono associate all'entità tramite `vendor_data`. Ogni sessione viene eseguita tramite il [workflow](https://docs.didit.me/it/console/workflows.md) configurato: verifica dell'identità, rilevamento della vitalità, confronto facciale, AML, documenti, ricerca nel registro per KYB, e così via.

Le sessioni completate aggiornano i contatori aggregati dell'entità:

* `session_count`, `approved_count`, `declined_count`, `in_review_count`
* mappa `features`: lo stato più recente di ciascuna funzionalità in tutte le sessioni (ad esempio `{ "id_verification": "APPROVED", "aml": "IN_REVIEW" }`)
* I campi del profilo vengono propagati dalla sessione approvata più recente (ad esempio `full_name`, `date_of_birth`, `portrait_image`).

**3. Utilizzo attivo**

Quando un'entità ha una o più sessioni approvate, puoi:

* **Inviare transazioni** che fanno riferimento all'entità tramite `vendor_data` nel payload della transazione
* **Eseguire il monitoraggio AML continuo**: nuove scansioni periodiche delle liste di sanzioni / PEP / notizie negative
* **Rieseguire la verifica secondo una pianificazione**: creare nuove sessioni per lo stesso `vendor_data` a intervalli regolari
* **Aggregare i segnali di rischio** tra sessioni e transazioni

**4. Transizioni di stato**

Il cambio di stato dell'entità avviene in modo automatico o manuale.

**Transizioni automatiche**

* `ACTIVE → FLAGGED` quando una transazione supera la soglia di revisione oppure una regola aggiunge l'entità a una watchlist.
* `ACTIVE → BLOCKED` quando una biometria facciale corrisponde a una voce della blocklist.

Una sessione rifiutata non inserisce l'entità in blocklist, quindi lo stato non cambia. Inserire in blocklist un soggetto rifiutato è un passaggio manuale: aggiungi la voce dalla [pagina Blocklist](https://docs.didit.me/it/console/blocklist-users.md) oppure tramite la [Lists API](https://docs.didit.me/it/management-api/lists/overview.md). Una voce di tipo `USER` (il `vendor_data`) imposta lo stato su `BLOCKED`.

**Le transizioni manuali** avvengono quando un analista modifica lo stato dalla console oppure quando chiami l'endpoint `update-status`.

Ogni transizione emette un webhook `user.status.updated` oppure `business.status.updated`.

**5. Eliminazione**

Le entità si eliminano tramite `POST /v3/users/delete/` oppure `POST /v3/businesses/delete/` (in batch). Il record dell'entità viene rimosso in modo permanente. Eliminare un User rimuove anche ogni [modello biometrico](https://docs.didit.me/it/management-api/biometric-templates/overview.md) conservato per lui dopo l'eliminazione delle sessioni, così la persona non produce più corrispondenze nel rilevamento dei duplicati e nella Ricerca facciale.

Questi endpoint non coprono le sessioni di verifica, né le transazioni. Elimina le sessioni con [Delete Session](https://docs.didit.me/it/sessions-api/delete-session.md) oppure [Batch Delete Sessions](https://docs.didit.me/it/management-api/sessions/batch-delete.md); le transazioni si eliminano dalla Console.

## Timestamp delle attività

Le entità tengono traccia dell'attività per aiutarti a individuare profili inattivi o attivi:

| Timestamp | Aggiornato quando |
| - | - |
| `first_session_at` | È stata creata la prima sessione per questa entità |
| `last_session_at` | È stata creata o aggiornata la sessione più recente |
| `last_activity_at` | È avvenuta una modifica: sessione, transazione, cambio di stato, aggiornamento del profilo |

Usa questi timestamp per filtrare le entità inattive, pianificare le nuove verifiche o avviare il monitoraggio continuo.

## Eventi emessi durante il ciclo di vita

| Fase del ciclo di vita | Webhook emessi |
| - | - |
| Creazione (automatica dalla sessione) | `status.updated` (sessione), `user.data.updated` oppure `business.data.updated` |
| Verifica | `status.updated` (sessione), `data.updated` |
| Cambio di stato | `user.status.updated` oppure `business.status.updated` |
| Transazione inviata | `transaction.created` |
| Stato della transazione modificato | `transaction.status.updated` |

Per il formato dei payload e la semantica di consegna, consulta i [webhook delle entità](https://docs.didit.me/it/entities/webhooks.md).

## Passaggi successivi

> [card] [Collegamento dei dati del fornitore](https://docs.didit.me/it/entities/vendor-data-linking.md)
>
> Come `vendor_data` collega tra loro sessioni, transazioni ed entità.

> [card] [Operazioni sulle entità User](https://docs.didit.me/it/entities/users/operations.md)
>
> Creare, aggiornare, cambiare lo stato ed eliminare le entità User.

> [card] [Operazioni sulle entità Business](https://docs.didit.me/it/entities/businesses/operations.md)
>
> Creare, aggiornare, cambiare lo stato ed eliminare le entità Business.


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