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

# Blocklist utenti: blocca volti, documenti, email

> Come Didit applica i blocchi sulle entità utente: tipi di identificatori, verifica del blocco e come aggiungere o rimuovere una voce.

Blocklist impediscono agli utenti che non hanno superato i tuoi controlli di compliance di creare nuove sessioni o eseguire nuove transazioni. Didit supporta le blocklist per **tipo di identificatore**, così puoi bloccare lo stesso soggetto a rischio su più dati (volto, documento, email, telefono, vendor\_data dell'utente).

## Tipi di identificatore supportati per gli Utenti

| Tipo | Chiave | Corrispondenza quando… |
| - | - | - |
| Volto | `FACE` | Il selfie per il rilevamento della vitalità di una nuova sessione corrisponde al volto presente in blocklist |
| Numero del documento | `DOCUMENT` | Il numero di documento di una nuova richiesta di invio del documento corrisponde al numero di documento presente nella blocklist |
| Email | `EMAIL` | Una nuova sessione o transazione usa l'email presente in blocklist |
| Telefono | `PHONE` | Una nuova sessione o transazione usa il telefono presente in blocklist |
| Indirizzo IP | `IP_ADDRESS` | L'IP di chi invia corrisponde: sono supportati singoli IP (`1.2.3.4`) e intervalli CIDR (`10.0.0.0/8`) |
| Impronta del dispositivo | `DEVICE_FINGERPRINT` | L'impronta del dispositivo di chi invia corrisponde |
| Utente | `USER` | La sessione o la transazione usa il `vendor_data` presente in blocklist |

Ogni tipo di identificatore viene applicato nel punto naturale di contatto:

* Volto e documento: applicati durante una nuova sessione.
* Email e telefono: applicati durante un passaggio della sessione che li raccoglie, oppure nel payload di una transazione.
* IP e dispositivo: applicati durante l'Analisi dispositivo e IP in una sessione.
* vendor\_data dell'utente: applicato durante la creazione di una sessione o di una transazione.

## Come avviene l'inserimento in blocklist

> [!NOTE]
>
> Una sessione rifiutata non inserisce nessuno in blocklist. La sessione termina con stato `Declined`, l'Utente resta `ACTIVE` e non viene scritta alcuna voce in lista, quindi la stessa persona può avviare un'altra sessione. L'inserimento in blocklist è un passaggio manuale: aggiungi la voce dalla [pagina Blocklist](https://docs.didit.me/it/console/blocklist-users.md) oppure con la [Lists API](https://docs.didit.me/it/management-api/lists/overview.md). Una voce di tipo `USER` (il `vendor_data` dell'utente) imposta anche lo stato dell'Utente su `BLOCKED`.

**1. Automatico: in caso di corrispondenza con la blocklist**

Quando una sessione in arrivo corrisponde a una voce esistente nella blocklist, la sessione viene rifiutata automaticamente con un codice motivo come `blocked_face`, `blocked_document`, `blocked_email` e simili.

**2. Manuale: dalla console**

Un analista inserisce un utente nella blocklist da *Utenti → \[utente] → Azioni → Aggiungi alla blocklist*, scegliendo uno o più identificatori da acquisire.

**3. Programmatico: tramite la Lists API**

Usa la [Lists API](https://docs.didit.me/it/management-api/lists/overview.md) per aggiungere voci in modo programmatico. È la stessa API che la console utilizza internamente.

## Liste di sistema e liste personalizzate

Ogni applicazione dispone di **blocklist di sistema**, una per tipo di identificatore, che Didit gestisce automaticamente. Non puoi rinominarle né eliminarle. Le liste personalizzate sono tue: le crei, le nomini e ne definisci l'ambito.

| Lista | Creata da | Descrizione |
| - | - | - |
| System Face Blocklist | Didit | Blocklist canonica dei volti per l'applicazione |
| System Document Blocklist | Didit | Blocklist canonica dei numeri di documento |
| System Email Blocklist | Didit | Blocklist canonica delle email |
| System Phone Blocklist | Didit | Blocklist canonica dei telefoni |
| System User Blocklist | Didit | Identificatori `vendor_data` bloccati |
| Blocklist personalizzate | Tu | Liste con ambito definito, ad esempio per regione, per partner o per livello di rischio |

## Aggiungere un utente alla blocklist tramite API

Usa la [Lists API](https://docs.didit.me/it/management-api/lists/overview.md) per aggiungere una voce in blocklist. Per bloccare un utente tramite `vendor_data`, aggiungi una voce di tipo USER alla blocklist corrispondente:

1. [Elenca tutte le liste](https://docs.didit.me/it/management-api/lists/list.md) filtrando per `entry_type=user` e `is_system=true`, per trovare la System User Blocklist.
2. [Crea una voce](https://docs.didit.me/it/management-api/lists/create-entry.md) in quella lista, con `value` impostato sul `vendor_data` dell'utente.

Per bloccare un utente tramite il volto, consulta [Volti e biometria](https://docs.didit.me/it/entities/users/faces-and-biometrics.md#caricare-un-volto-nella-blocklist). Per bloccare tramite email, telefono, documento o IP, usa la blocklist di sistema corrispondente con l'identificatore appropriato in `value`.

## Flusso di applicazione delle regole

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Didit
    participant Lists as Blocklist check
    participant Workflow
    Client->>Didit: POST /v3/session/ (vendor_data=user-42)
    Didit->>Lists: Does user-42 match a USER blocklist?
    Lists-->>Didit: Match found
    Didit-->>Client: Session auto-declined (reason: blocked_user)
```

Per le blocklist di volti e documenti, il controllo avviene nel passaggio di verifica:

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Didit
    participant Lists as Face Blocklist
    User->>Didit: Liveness capture
    Didit->>Lists: Embedding search
    Lists-->>Didit: Match similarity > threshold
    Didit-->>User: Session declined (reason: blocked_face)
```

## Rimuovere dalla blocklist

* **Console**: *Blocklist → \[tipo] → azioni sulla riga → Rimuovi*.
* **API**: usa l'endpoint [Elimina voce](https://docs.didit.me/it/management-api/lists/delete-entry.md) con l'UUID della lista e l'UUID della voce.

Rimuovere la voce non riporta automaticamente l'utente allo stato `ACTIVE`. Se vuoi consentire nuove sessioni, usa `PATCH /v3/users/{vendor_data}/update-status/` per modificare lo stato.

## Registro di audit della blocklist

Ogni aggiunta o rimozione in una blocklist viene registrata nel [registro di audit](https://docs.didit.me/it/console/audit-logs.md):

* Chi ha aggiunto la voce (email dell'utente oppure `'system'`, `'api'`).
* Quando.
* Il `comment` facoltativo che spiega il motivo.
* La sessione o transazione collegata, se la voce è stata generata automaticamente.

## Prossimi passi

> [card] [Lists API](https://docs.didit.me/it/management-api/lists/overview.md)
>
> Riferimento completo dell'API per blocklist e allowlist.

> [card] [Blocklist in console](https://docs.didit.me/it/console/blocklist-users.md)
>
> Gestisci le blocklist dall'interfaccia.

> [card] [Volti e biometria](https://docs.didit.me/it/entities/users/faces-and-biometrics.md)
>
> Come funzionano le blocklist dei volti.


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