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

# Avvisi e codici di rischio della verifica telefonica

> Tutti i codici di rischio Didit per la verifica telefonica: HIGH_RISK_PHONE_NUMBER, VOIP_NUMBER_DETECTED, numeri monouso, blocklist e limiti OTP.

La funzionalità Verifica telefonica emette **avvisi** ogni volta che si attiva un segnale di rischio sul flusso OTP o sul numero stesso: un numero noto come non valido o a rischio, una linea VoIP o usa e getta, il superamento del limite di tentativi OTP o una corrispondenza con la sessione di un altro utente. Questa pagina elenca ciascun codice, cosa lo attiva e come configurare la risposta del workflow.

## Panoramica

Gli avvisi sono contrassegnati con la funzionalità `PHONE`. Compaiono sotto `phone_verifications[].warnings[]` in `GET /v3/session/{sessionId}/decision/` e seguono la struttura standard dell'[oggetto avviso](https://docs.didit.me/it/reference/data-models.md#oggetto-avviso) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). Ciascun avviso viene inoltre instradato nel registro per sessione in modo da comparire nella Business Console nella sezione Telefono.

Alcuni avvisi sono trigger di **rifiuto automatico vincolante**: impostano sempre lo stato della funzionalità su `Declined`. Altri sono mappati su un'**azione configurabile** (`DECLINE`, `REVIEW` o `NO_ACTION`, a seconda dell'impostazione) definita nelle impostazioni del workflow, in modo che lo stesso codice di rischio possa rifiutare un workflow e limitarsi a segnalarne un altro.

## Condizioni di rifiuto automatico

I seguenti avvisi rifiutano sempre il passaggio di Verifica telefonica indipendentemente dalla configurazione e presentano sempre `log_type: "error"`:

* `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`: l'utente ha esaurito il limite di tentativi OTP: per impostazione predefinita 2 invii di codice errati (`phone_max_check_attempts`) o più di 2 invii OTP (`phone_max_retries`), entrambi regolabili per nodo del workflow. L'API standalone per la verifica telefonica consente 3 tentativi di inserimento del codice.
* `PHONE_NUMBER_IN_BLOCKLIST`: il numero è presente nella tua blocklist gestita tramite l'[API Lists](https://docs.didit.me/it/management-api/lists/overview.md) oppure corrisponde a una sessione inserita in blocklist.

`HIGH_RISK_PHONE_NUMBER`: il livello antifrode del provider di consegna rifiuta di inviare l'OTP (invio `Blocked`): il blocco comporta il rifiuto per impostazione predefinita ma **non è più incondizionato**: consulta [`high_risk_phone_action`](#invii-bloccati) più avanti.

## Rischi configurabili

Ciascuno dei seguenti rischi è associato a un'impostazione del workflow che puoi configurare su `DECLINE`, `REVIEW` o `NO_ACTION` (il valore predefinito: l'avviso viene registrato senza influire sullo stato). L'azione configurata imposta anche il `log_type` dell'avviso: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

| Impostazione | Codice di rischio | Si attiva quando |
| - | - | - |
| `voip_number_action` | `VOIP_NUMBER_DETECTED` | Il carrier identifica la linea come di tipo `voip`, `isp` o `vpn`. |
| `disposable_number_action` | `DISPOSABLE_NUMBER_DETECTED` | La verifica individua il numero come appartenente a un provider temporaneo o usa e getta. |
| `duplicated_phone_number_action` | `DUPLICATED_PHONE_NUMBER` | Il numero corrisponde a un'altra sessione di qualunque stato appartenente a un utente finale diverso. Ignorato quando il numero è inserito nella allowlist. |

Il rilevamento dei duplicati viene eseguito all'interno della tua applicazione per le verifiche telefoniche KYC, KYB e tramite API standalone, e raggruppa le sessioni per `vendor_data`: le sessioni che condividono lo stesso `vendor_data` vengono trattate come un unico utente finale e sono escluse dai risultati delle corrispondenze. Se lasci vuoto `vendor_data`, ogni sessione viene considerata come un utente distinto.

### Invii bloccati

`HIGH_RISK_PHONE_NUMBER` segue lo stesso schema con un insieme di opzioni più ristretto, poiché un invio rifiutato dal provider non può essere approvato:

| Impostazione | Codice di rischio | Si attiva quando |
| - | - | - |
| `high_risk_phone_action` | `HIGH_RISK_PHONE_NUMBER` | Il livello antifrode del provider di consegna ha rifiutato di inviare l'OTP (invio `Blocked`). Accetta solo `DECLINE` o `REVIEW` e il valore predefinito è `DECLINE`. |

L'impostazione viene applicata **solo quando ogni blocco ad alto rischio sul passaggio presenta in `additional_data.risk_factors` esattamente `["device_attribute"]`**: il segnale del provider "questo dispositivo appare sospetto", ovvero ciò che si attiva sulle normali linee mobili. Qualsiasi altro fattore di rischio, qualsiasi combinazione che si limiti a includere `device_attribute` o un blocco privo di fattori di rischio comporta il rifiuto a prescindere dall'impostazione. Il motivo del blocco (`repeated_attempts`, `suspicious` o `spam`) è un campo separato, restituito in `additional_data.blocked_reason`.

Indipendentemente dall'impostazione, un numero presente in una allowlist telefonica creata tramite l'[API Lists](https://docs.didit.me/it/management-api/lists/overview.md) non viene mai rifiutato automaticamente per un invio bloccato: il passaggio passa a **In revisione**, l'avviso presenta `log_type: "warning"` e `additional_data.phone_number_in_allowlist` è `true`.

## Limiti dei tentativi di verifica

La funzionalità Verifica telefonica applica un limite massimo rigido sui tentativi di OTP per prevenire abusi:

* **Tentativi di inserimento del codice** — Valore predefinito di **2** invii errati (`phone_max_check_attempts`) prima che il passaggio si concluda come `Declined` con `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`. L'API telefonica autonoma consente **3** tentativi di inserimento del codice per verifica.
* **Tentativi di invio** — Valore predefinito di **2** invii totali (`phone_max_retries`): l'invio iniziale più un reinvio. Un'ulteriore richiesta di invio conclude il passaggio e genera `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`.
* **Validità dell'OTP** — Un OTP in attesa è valido per **5 minuti dal primo invio**; i nuovi tentativi non estendono questa finestra.

Entrambi i limiti sono configurabili per nodo del workflow. Indipendentemente da questi limiti, il livello antifrode del provider di consegna può bloccare direttamente un invio (motivo `repeated_attempts`, `suspicious` o `spam`): questo genera `HIGH_RISK_PHONE_NUMBER`, non l'avviso relativo ai tentativi.

## Avvisi generati

| Tag | `log_type` | Descrizione |
| - | - | - |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | `error` (sempre) | L'utente ha superato il limite di inserimento del codice OTP o di invio. Rifiuto automatico. |
| `HIGH_RISK_PHONE_NUMBER` | Segue `high_risk_phone_action`, o `warning` se in allowlist | Il provider di consegna ha bloccato l'invio dell'OTP. Viene rifiutata per impostazione predefinita; imposta `high_risk_phone_action` su `REVIEW` per indirizzare invece un blocco basato solo sui segnali del dispositivo allo stato in revisione (vedi [Invii bloccati](#invii-bloccati)). Anche un numero presente in una allowlist telefonica passa allo stato in revisione. `additional_data`: `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`. |
| `PHONE_NUMBER_IN_BLOCKLIST` | `error` (sempre) | Il numero è presente in una blocklist creata tramite l'[API Lists](https://docs.didit.me/it/management-api/lists/overview.md) o corrisponde a una sessione inserita in blocklist. Rifiuto automatico. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }` (tutti `null` per una corrispondenza diretta nella lista). |
| `PHONE_NUMBER_IN_ALLOWLIST` | `information` | Il numero corrispondeva ad altre sessioni ma è presente in una allowlist creata tramite l'[API Lists](https://docs.didit.me/it/management-api/lists/overview.md), quindi le azioni per numero duplicato vengono ignorate. `additional_data`: `{ phone_number }`. |
| `DISPOSABLE_NUMBER_DETECTED` | Segue `disposable_number_action` | Il numero appartiene a un provider temporaneo o usa e getta, spesso utilizzato per eludere la tracciabilità. |
| `VOIP_NUMBER_DETECTED` | Segue `voip_number_action` | Il numero corrisponde a una linea `voip`, `isp` o `vpn` anziché a una linea mobile o fissa standard. |
| `DUPLICATED_PHONE_NUMBER` | Segue `duplicated_phone_number_action` | Il numero corrisponde a un'altra sessione — di qualsiasi stato — appartenente a un utente finale diverso (raggruppate in base a `vendor_data`). `additional_data`: `{ duplicated_session_id, duplicated_session_number, api_service }`. |

## Corrispondenze tra sessioni

Quando un numero viene rilevato in altre sessioni o nella tua blocklist, tali corrispondenze compaiono anche in `phone_verifications[].matches[]` (con un limite massimo di 5 voci). Ciascuna corrispondenza include `session_id`, `session_number`, `vendor_data`, `verification_date`, `phone_number`, `status`, `is_blocklisted`, `api_service` e un campo `source` con valore `session` (un'altra sessione con lo stesso numero, di qualsiasi stato) o `list_entry` (una corrispondenza sintetica della blocklist anteposta all'array). Se il numero corrente è presente nella tua allowlist telefonica, Didit conserva l'evidenza della corrispondenza ma genera `PHONE_NUMBER_IN_ALLOWLIST` anziché applicare l'azione per numero duplicato. Consulta il [report di Verifica telefonica](https://docs.didit.me/it/core-technology/phone-verification/report-phone-verification.md#corrispondenze-tra-sessioni) per lo schema completo delle corrispondenze.

## Esempio

Un invio bloccato (`HIGH_RISK_PHONE_NUMBER`) su un numero VoIP, con `voip_number_action` configurato su `REVIEW`:

```json theme={null}
{
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "HIGH_RISK_PHONE_NUMBER",
      "additional_data": { "blocked_reason": "suspicious" },
      "log_type": "error",
      "short_description": "High risk phone number",
      "long_description": "The system detected that the phone number is a high risk phone number, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ]
}
```

## Tipi di avviso

A ciascun rischio viene assegnata una gravità in base alla configurazione della tua applicazione. I livelli di gravità si suddividono in tre categorie:

## Correlati

* [Panoramica sulla Verifica telefonica](https://docs.didit.me/it/core-technology/phone-verification/overview.md) — comportamento della funzionalità, prezzi, canali supportati.
* [Report di Verifica telefonica](https://docs.didit.me/it/core-technology/phone-verification/report-phone-verification.md) — struttura completa della risposta inclusi `lifecycle[]` e `matches[]`.
* [Modelli di dati — verifica telefonica](https://docs.didit.me/it/reference/data-models.md#verifica-telefonica) — schema canonico campo per campo.
* [API di gestione — Liste](https://docs.didit.me/it/management-api/lists/overview.md) — gestione della blocklist telefonica utilizzata da `PHONE_NUMBER_IN_BLOCKLIST`.


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