> ## 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 Sessions: verifica dell'identità KYC e KYB unificata

> Didit: API Sessions unifica KYC e KYB su un endpoint. Prezzo a consumo, 220+ paesi, 14,000+ documenti, $10 di credito gratuito al mese.

Le sessioni sono l'unità di verifica su Didit. Quando avvii una verifica, viene creata una **sessione**; al termine della verifica, la sessione contiene il payload completo della decisione. La stessa API delle sessioni gestisce entrambi i tipi:

| Tipo | Cosa verifica | Il payload della decisione include |
| - | - | - |
| **Sessione di Verifica degli utenti (KYC)** | Una singola persona | Verifica dell'identità, rilevamento della vitalità, confronto facciale, POA, NFC, validazione su database, verifica telefonica, verifica email, AML, questionari, Analisi dispositivo e IP |
| **Sessione di Verifica aziendale (KYB)** | Un'azienda / entità giuridica | Controllo nel registro delle imprese, persone chiave (amministratori/UBO), verifiche dei documenti, verifica telefonica, verifica email, AML, questionari, Analisi dispositivo e IP |

Nella lezione dell'Academy su ciò che vedono gli utenti, il capitolo al minuto 5:34 mette a confronto il flusso ospitato e la creazione di schermate proprie, ed è esattamente il compromesso che questa API decide al posto tuo.

[Il flusso ospitato contro la creazione di schermate proprie, Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=334\&rel=0\&playsinline=1)

## Il tipo è determinato dal workflow

Quando [crei una sessione](https://docs.didit.me/it/sessions-api/create-session.md), passi un `workflow_id`. Il tipo del workflow determina se la sessione è una Verifica degli utenti o una Verifica aziendale: chi chiama l'API non sceglie il tipo separatamente. I workflow KYB creano sessioni di Verifica aziendale; i workflow KYC creano sessioni di Verifica degli utenti.

## Discriminante `session_kind`

Ogni risposta relativa a una sessione (da creazione, lettura, elenco, aggiornamento dello stato, condivisione e importazione) include un campo di primo livello:

```json theme={null}
{
  "session_id": "...",
  "session_kind": "user",
  ...
}
```

* `"user"`: la sessione è una **Sessione di Verifica degli utenti (KYC)**. La risposta contiene gli array di funzionalità specifici per l'utente.
* `"business"`: la sessione è una **Sessione di Verifica aziendale (KYB)**. La risposta contiene gli array di funzionalità specifici per l'azienda.

Usa questo campo per determinare la struttura della risposta lato client.

> [!NOTE]
>
> I valori dell'enum sono gli identificativi brevi `"user"` e `"business"`, che teniamo brevi per comodità dell'API. I nomi completi **Verifica degli utenti (KYC)** e **Verifica aziendale (KYB)** sono usati nella documentazione per chiarezza.

## Array di funzionalità per tipo

Gli array di funzionalità presenti in una decisione dipendono dal tipo. I campi assenti in un tipo non compaiono nella risposta di quel tipo (nessun null, nessun segnaposto):

| Array di funzionalità | Verifica degli utenti (KYC) | Verifica aziendale (KYB) |
| - | :-: | :-: |
| `id_verifications` | ✅ | — |
| `liveness_checks` | ✅ | — |
| `face_matches` | ✅ | — |
| `nfc_verifications` | ✅ | — |
| `poa_verifications` | ✅ | — |
| `database_validations` | ✅ | — |
| `registry_checks` | — | ✅ |
| `document_verifications` | — | ✅ |
| `key_people_checks` | — | ✅ |
| `aml_screenings` | ✅ | ✅ |
| `phone_verifications` | ✅ | ✅ |
| `email_verifications` | ✅ | ✅ |
| `questionnaire_responses` | ✅ | ✅ |
| `ip_analyses` | ✅ | ✅ |
| `reviews` | ✅ | ✅ |
| `contact_details` | ✅ | ✅ |

## Campi di primo livello comuni

Ogni sessione (di entrambi i tipi) include questi campi:

| Campo | Descrizione |
| - | - |
| `session_id` | UUID della sessione |
| `session_kind` | `"user"` (Verifica degli utenti / KYC) o `"business"` (Verifica aziendale / KYB) |
| `session_number` | Numero progressivo all'interno dell'applicazione |
| `session_url` | URL della pagina di verifica ospitata |
| `status` | Stato complessivo della sessione: `APPROVED`, `DECLINED`, `IN_REVIEW`, `IN_PROGRESS`, ecc. |
| `workflow_id` | UUID del workflow utilizzato |
| `vendor_data` | Il tuo identificativo per l'entità. [Scopri di più](https://docs.didit.me/it/entities/vendor-data-linking.md) |
| `metadata` | JSON in formato libero che hai allegato alla creazione |
| `callback` | URL di callback facoltativo |
| `features` | Elenco di funzionalità separate da virgole che il workflow esegue |
| `expected_details` | Payload facoltativo con i dati attesi, per la validazione incrociata |
| `created_at`, `expires_at` | Timestamp |

## Endpoint supportati

Gli endpoint seguenti accettano entrambi i tipi. Non esistono percorsi separati `/v3/business-session/*`.

| Endpoint | Funziona per |
| - | - |
| [`POST /v3/session/`](https://docs.didit.me/it/sessions-api/create-session) | Crea una sessione di Verifica degli utenti o di Verifica aziendale in base al tipo di workflow |
| [`GET /v3/session/{id}/decision/`](https://docs.didit.me/it/sessions-api/retrieve-session) | Recupera entrambi i tipi: viene instradato in base a `session_id` |
| [`GET /v3/sessions/`](https://docs.didit.me/it/sessions-api/list-sessions) | Elenca entrambi i tipi. Usa il parametro di query `session_kind` per filtrare |
| [`PATCH /v3/session/{id}/update-status/`](https://docs.didit.me/it/sessions-api/update-status) | Aggiorna entrambi i tipi |
| [`DELETE /v3/session/{id}/delete/`](https://docs.didit.me/it/sessions-api/delete-session) | Elimina entrambi i tipi |
| [`GET /v3/session/{id}/generate-pdf/`](https://docs.didit.me/it/sessions-api/generate-pdf) | Genera un PDF per entrambi i tipi: usa il modello di Verifica degli utenti o di Verifica aziendale |
| [`POST /v3/session/{id}/share/`](https://docs.didit.me/it/sessions-api/share-session/share) | Il token di condivisione include `session_kind` |
| [`POST /v3/session/import-shared/`](https://docs.didit.me/it/sessions-api/share-session/import) | Importa entrambi i tipi: conserva `session_kind` dal token |

## Come funzionano le ricerche

Le sessioni di Verifica degli utenti e di Verifica aziendale sono due tipi distinti. Gli ID sono UUID, quindi le collisioni sono impossibili. Quando chiami un endpoint con un `session_id`, Didit:

1. Cerca l'id prima nella tabella delle Verifiche degli utenti (copre la maggior parte del traffico).
2. Se non lo trova, cerca nella tabella delle Verifiche aziendali.
3. Restituisce 404 se nessuna delle due tabelle contiene una corrispondenza.

Non è mai necessario indicare all'API quale tipo stai cercando.

## Gli stati sono identici

I valori di stato sono gli stessi per entrambi i tipi, e l'API li restituisce esattamente come scritti qui: `"Not Started"`, `"In Progress"`, `"Approved"`, `"Declined"`, `"In Review"`, `"Abandoned"`, `"Expired"`, `"Kyc Expired"`, `"Resubmitted"`, `"Awaiting User"`. La corrispondenza è esatta e distingue maiuscole e minuscole. Consulta [stati di verifica](https://docs.didit.me/it/integration/verification-statuses.md) per il riferimento completo.

## Webhook

Gli eventi webhook includono già un campo `session_kind`, così i gestori dei webhook possono smistare per tipo:

| Evento | Tipo | Si attiva quando |
| - | - | - |
| `status.updated` | Entrambi | Lo stato di una sessione è cambiato. Il payload contiene `session_kind: "user"` o `"business"`. |
| `data.updated` | Entrambi | I dati di una sessione sono cambiati (risultati delle funzionalità, aggiornamento del registro, monitoraggio AML continuo). Il payload contiene `session_kind`. |
| `business.status.updated` / `business.data.updated` | Entità aziendale | L'entità aziendale collegata è cambiata. |
| `user.status.updated` / `user.data.updated` | Entità utente | L'entità utente collegata è cambiata. |

Per la verifica della firma e la semantica dei nuovi tentativi, consulta [webhook](https://docs.didit.me/it/integration/webhooks.md). Per il catalogo degli eventi della Verifica aziendale, consulta [webhook KYB](https://docs.didit.me/it/business-verification/webhooks.md).

## Prossimi passi

> [card] [Crea sessione](https://docs.didit.me/it/sessions-api/create-session.md)
>
> Avvia una verifica: Verifica degli utenti o Verifica aziendale.

> [card] [Recupera sessione](https://docs.didit.me/it/sessions-api/retrieve-session.md)
>
> Recupera la decisione. Funziona per entrambi i tipi.

> [card] [Elenca sessioni](https://docs.didit.me/it/sessions-api/list-sessions.md)
>
> Filtra per `session_kind`.

> [card] [Aggiorna stato](https://docs.didit.me/it/sessions-api/update-status.md)
>
> Approva, rifiuta, metti in revisione, invia di nuovo.

> [card] [Genera PDF](https://docs.didit.me/it/sessions-api/generate-pdf.md)
>
> Report PDF per tipo.

> [card] [Condividi e importa](https://docs.didit.me/it/sessions-api/share-session/overview.md)
>
> Sposta le sessioni tra applicazioni.


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