Report di verifica telefonica: JSON OTP e operatore

Il report di Verifica telefonica acquisisce l’esito completo di una procedura di verifica OTP telefonica: a chi abbiamo inviato il codice, quale operatore e canale lo hanno gestito, quanti tentativi sono stati necessari, se il numero è usa e getta o VoIP, ed eventuali corrispondenze del numero con la tua blocklist o con le sessioni di altri utenti. Questa pagina documenta la struttura JSON restituita dall’endpoint di decisione, consentendoti di analizzare gli esiti dell’OTP, i metadati dell’operatore e i flag di rischio per ciascun numero verificato.

Report di verifica telefonica di Didit che mostra l'esito dell'OTP, i metadati dell'operatore e i flag di rischio

Panoramica

Un report telefonico viene generato ogni volta che un nodo del workflow esegue la funzionalità di Verifica telefonica. Ciascun report rappresenta una procedura di verifica OTP associata a un singolo numero di telefono e contiene:

Il numero di telefono suddiviso in prefisso, numero nazionale e formato E.164 completo, oltre al codice paese ISO e al nome del paese.
Metadati dell’operatore (name, type) ricavati dalla rete di destinazione.
Flag di rischio booleani (is_disposable, is_virtual) derivati dall’analisi della tipologia di linea.
L’effettivo canale di consegna utilizzato (verification_method) e il conteggio dei tentativi di invio dell’OTP.
Un registro cronologico lifecycle[] di ogni invio, nuovo tentativo, evento di consegna e tentativo di verifica del codice.
Un array matches[] che evidenzia lo stesso numero presente in altre sessioni — in qualsiasi stato, tra KYC, KYB e verifiche API autonome — o nella tua blocklist.
Un array warnings[] — eventi di rischio generati durante la verifica (consulta gli Avvisi di Verifica telefonica).
Un node_id che identifica quale nodo del grafo del workflow ha generato il report (solo per sessioni V3).

Nei flussi di verifica ospitati, Didit gestisce lo scambio dell’OTP per te. Per le integrazioni API dirette, lo stesso flusso si articola in due chiamate: POST /v3/phone/send/ per recapitare il codice e POST /v3/phone/check/ per convalidare l’inserimento dell’utente. Un OTP in attesa è valido per 5 minuti dal primo invio (i nuovi tentativi non estendono l’intervallo). Nelle sessioni del workflow gli utenti hanno a disposizione per impostazione predefinita 2 tentativi di invio dell’OTP (phone_max_retries) e 2 tentativi di inserimento del codice (phone_max_check_attempts), entrambi configurabili per singolo nodo del workflow; l’esaurimento di uno di questi limiti conclude il passaggio come Declined con VERIFICATION_CODE_ATTEMPTS_EXCEEDED. L’API telefonica autonoma consente 3 tentativi di inserimento del codice per verifica.

Dove appare nelle risposte API

L’endpoint di decisione (GET /v3/session/{sessionId}/decision/) restituisce i report telefonici con la chiave di array al plurale phone_verifications. L’array contiene una voce per ciascun nodo di Verifica telefonica presente nel grafo del workflow — in genere una sola, ma i flussi di step-up possono generarne diverse.

{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "phone_verifications": [
    { "status": "Approved", "node_id": "feature_phone_1", "...": "..." }
  ]
}

Un valore null indica che nessun passaggio di Verifica telefonica è stato ancora eseguito. Itera sull’array (invece di leggere solo phone_verifications[0]) quando il tuo workflow può raccogliere più di un numero di telefono.

Schema

Lo schema canonico campo per campo si trova nella pagina Modelli di dati.

interface PhoneVerification {
  status: "Not Finished" | "Approved" | "Declined" | "In Review" | "Expired";
  phone_number_prefix: string;       // E.g. "+34"
  phone_number: string;              // National number, no prefix
  full_number: string;               // Full E.164, e.g. "+34600600600"
  country_code: string;              // ISO 3166-1 alpha-2, e.g. "ES"
  country_name: string;
  carrier: {
    name: string;
    type:                              // From LineTypeChoices
      | "mobile" | "fixed_line" | "voip" | "isp" | "vpn"
      | "toll_free" | "premium_rate" | "shared_cost" | "local_rate"
      | "satellite" | "pager" | "payphone" | "voice_mail"
      | "calling_cards" | "service" | "short_codes_commercial"
      | "universal_access" | "other" | "unknown";
  };
  is_disposable: boolean;            // Temporary / burner number
  is_virtual: boolean;               // true when carrier.type is voip, isp or vpn
  verification_method:               // Actual channel that delivered the OTP
    | "sms" | "whatsapp" | "telegram" | "voice" | "rcs" | "viber" | "zalo";
  verification_attempts: number;     // OTP send attempts (initial send + resends)
  verified_at: string | null;        // ISO 8601, set when a valid OTP was entered
  warnings: Warning[];               // Risk events emitted during verification
  lifecycle: PhoneLifecycleEvent[];  // OTP send/retry/delivery/check timeline
  matches: PhoneMatch[];             // Cross-session / blocklist matches (max 5)
  node_id: string;                   // Workflow graph node that produced this report
}

Valori di stato

Stato	Significato
`Not Finished`	L’invio dell’OTP è stato avviato, ma la verifica non è stata ancora finalizzata.
`Approved`	L’utente ha inserito un OTP valido e non è stato rilevato alcun rischio che comporti il rifiuto.
`Declined`	È scattato un avviso di rifiuto automatico (blocklist, rischio elevato, tentativi superati) o è corrisposta un’azione di rischio configurata su `DECLINE`.
`In Review`	Un’azione di rischio impostata su `REVIEW` ha indirizzato il passaggio alla revisione manuale.
`Expired`	La finestra di 5 minuti per l’OTP è trascorsa senza un codice valido — si applica alle verifiche create tramite l’API telefonica autonoma.

Tipi di eventi del ciclo di vita

lifecycle[] è ordinato cronologicamente. Ciascun evento include type, timestamp, details e un importo fatturabile fee (quando applicabile):

Tipo di evento	Emesso quando
`PHONE_VERIFICATION_MESSAGE_SENT`	Viene effettuato il primo tentativo di invio dell’OTP sul canale richiesto.
`PHONE_VERIFICATION_RETRY_MESSAGE_SENT`	Viene effettuato un invio successivo dell’OTP dopo la richiesta di reinvio da parte dell’utente.
`PHONE_VERIFICATION_BLOCKED`	L’invio è stato bloccato (spam, attività sospetta, tentativi ripetuti, numero non valido).
`PHONE_DELIVERY_DELIVERED`	L’operatore ha confermato la consegna sul canale effettivamente utilizzato.
`PHONE_DELIVERY_UNDELIVERABLE`	L’operatore ha segnalato che non è stato possibile recapitare il messaggio.
`VALID_CODE_ENTERED`	L’utente ha inserito il codice OTP corretto.
`INVALID_CODE_ENTERED`	L’utente ha inserito un codice OTP errato (conta ai fini del limite di tentativi di inserimento del codice).
`PHONE_VERIFICATION_APPROVED`	Lo stato a livello di funzionalità è stato impostato su `Approved`.
`PHONE_VERIFICATION_DECLINED`	Lo stato a livello di funzionalità è stato impostato su `Declined`.
`PHONE_VERIFICATION_IN_REVIEW`	Lo stato a livello di funzionalità è stato impostato su `In Review`.
`PHONE_VERIFICATION_EXPIRED`	La finestra per l’OTP è trascorsa senza un codice valido.

Il payload details dipende dalla famiglia di eventi:

Eventi di invio (PHONE_VERIFICATION_MESSAGE_SENT, PHONE_VERIFICATION_RETRY_MESSAGE_SENT, PHONE_VERIFICATION_BLOCKED) — { status, reason, channel, actual_channel }. status è Success, Retry o Blocked; reason è null a meno che l’invio non sia stato bloccato (invalid_phone_number, repeated_attempts, suspicious, spam, unknown); channel è il canale richiesto e actual_channel è il canale che ha effettivamente consegnato il messaggio (ad esempio un invio WhatsApp deviato su SMS in fallback).
Eventi di consegna (PHONE_DELIVERY_DELIVERED, PHONE_DELIVERY_UNDELIVERABLE) — { channel, status } con status impostato su delivered o undeliverable.
Eventi di controllo (VALID_CODE_ENTERED, INVALID_CODE_ENTERED) — { code_tried, status } con status impostato su Approved, Declined, Failed o Expired or Not Found.
Eventi di stato finale — null, tranne PHONE_VERIFICATION_DECLINED / PHONE_VERIFICATION_IN_REVIEW, che contengono { "reason": "<risk code>" } (ad esempio PHONE_NUMBER_IN_BLOCKLIST).

Il valore fee su un evento di invio rappresenta il prezzo totale di quell’invio: il prezzo dell’operatore o di WhatsApp più la commissione Didit di $0.02, oppure solo la commissione Didit di $0.02 per un codice WhatsApp inviato dal tuo numero WhatsApp Business. È il prezzo stimato fino alla conferma della consegna, dopodiché diventa l’importo effettivo fatturato. Solo gli invii con stato Blocked sono garantiti come gratuiti: qualsiasi altro invio viene addebitato quando la verifica viene finalizzata o scade, anche se la consegna non è mai stata confermata o il messaggio è risultato non recapitabile. Gli eventi di consegna, di verifica e di stato presentano sempre fee: 0.

Corrispondenze tra sessioni

matches[] registra le altre sessioni nella stessa applicazione in cui è stato rilevato lo stesso numero — tra verifiche KYC, KYB e verifiche tramite API autonoma, indipendentemente dal loro stato — oltre ai riscontri di blocklist configurati nelle liste dell’API di gestione. Le sessioni che condividono il valore vendor_data della sessione corrente vengono escluse (lo stesso utente finale non genera corrispondenze con se stesso) e l’array è limitato a un massimo di 5 voci. Quando il numero è presente nella tua blocklist ma nessuna delle sessioni corrispondenti è inserita in blocklist, viene anteposta all’array una voce sintetica con source: "list_entry" (con tutti i campi della sessione impostati su null).

interface PhoneMatch {
  session_id: string | null;         // null when source = "list_entry"
  session_number: number | null;
  vendor_data: string | null;
  verification_date: string | null;  // ISO 8601, creation date of the matched session
  phone_number: string;
  status: string | null;             // Status of the matched session
  is_blocklisted: boolean;
  api_service: string | null;        // Set when the matched session came from a standalone API
  source: "session" | "list_entry";  // "list_entry" = manual blocklist hit
}

Esempi

Approvata — OTP WhatsApp, operatore mobile

{
  "status": "Approved",
  "phone_number_prefix": "+34",
  "phone_number": "600600600",
  "full_number": "+34600600600",
  "country_code": "ES",
  "country_name": "Spain",
  "carrier": { "name": "Orange", "type": "mobile" },
  "is_disposable": false,
  "is_virtual": false,
  "verification_method": "whatsapp",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:12:39.684292Z",
  "warnings": [],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:12:30.580554Z",
      "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" },
      "fee": 0.0509
    },
    {
      "type": "PHONE_DELIVERY_DELIVERED",
      "timestamp": "2025-08-24T09:12:31.000000Z",
      "details": { "channel": "whatsapp", "status": "delivered" },
      "fee": 0
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:12:39.662157Z",
      "details": { "code_tried": "123456", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_APPROVED",
      "timestamp": "2025-08-24T09:12:39.684292Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "feature_phone_1"
}

Rifiutata — numero VoIP in blocklist

L’utente ha inserito un OTP valido, ma la finalizzazione ha rilevato il numero nella blocklist dell’applicazione (rifiuto automatico) e ha segnalato il tipo di linea VoIP (voip_number_action è rimasto impostato su NO_ACTION, quindi viene registrato come information). Poiché nessuna sessione corrispondente è inserita in blocklist, il riscontro della blocklist appare come una corrispondenza sintetica list_entry.

{
  "status": "Declined",
  "phone_number_prefix": "+1",
  "phone_number": "5551234567",
  "full_number": "+15551234567",
  "country_code": "US",
  "country_name": "United States",
  "carrier": { "name": "VoIP Carrier", "type": "voip" },
  "is_disposable": false,
  "is_virtual": true,
  "verification_method": "sms",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:11:10.221340Z",
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "PHONE_NUMBER_IN_BLOCKLIST",
      "additional_data": { "blocklisted_session_id": null, "blocklisted_session_number": null, "api_service": null },
      "log_type": "error",
      "short_description": "Phone number in blocklist",
      "long_description": "The system detected that the phone number is in the blocklist, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "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"
    }
  ],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:11:00.000000Z",
      "details": { "status": "Success", "reason": null, "channel": "sms", "actual_channel": "sms" },
      "fee": 0.0509
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:11:10.221340Z",
      "details": { "code_tried": "482917", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_DECLINED",
      "timestamp": "2025-08-24T09:11:10.350000Z",
      "details": { "reason": "PHONE_NUMBER_IN_BLOCKLIST" },
      "fee": 0
    }
  ],
  "matches": [
    {
      "session_id": null,
      "session_number": null,
      "vendor_data": null,
      "verification_date": null,
      "phone_number": "+15551234567",
      "status": null,
      "is_blocklisted": true,
      "api_service": null,
      "source": "list_entry"
    }
  ],
  "node_id": "feature_phone_1"
}

Risorse correlate

Panoramica sulla Verifica telefonica — comportamento della funzionalità, prezzi, canali supportati.
Avvisi della Verifica telefonica — tutti i codici di rischio, trigger di rifiuto e azioni configurabili.
Modelli di dati — verifica telefonica — schema canonico campo per campo.
API telefonica autonoma — endpoint POST /v3/phone/send/ e POST /v3/phone/check/.
API di gestione — Liste — gestione della blocklist telefonica che alimenta matches[] con source: list_entry.

Autenticazione

Verifica

Monitoraggio

Piattaforma

Report di verifica telefonica: JSON OTP e operatore

Panoramica

Dove appare nelle risposte API

Schema

Valori di stato

Tipi di eventi del ciclo di vita

Corrispondenze tra sessioni

Esempi

Approvata — OTP WhatsApp, operatore mobile

Rifiutata — numero VoIP in blocklist

Risorse correlate

​Panoramica

​Dove appare nelle risposte API

​Schema

​Valori di stato

​Tipi di eventi del ciclo di vita

​Corrispondenze tra sessioni

​Esempi

​Approvata — OTP WhatsApp, operatore mobile

​Rifiutata — numero VoIP in blocklist

​Risorse correlate

Panoramica

Dove appare nelle risposte API

Schema

Valori di stato

Tipi di eventi del ciclo di vita

Corrispondenze tra sessioni

Esempi

Approvata — OTP WhatsApp, operatore mobile

Rifiutata — numero VoIP in blocklist

Risorse correlate