> ## 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. # Report di verifica telefonica: JSON OTP e operatore > Analizza i report di verifica telefonica Didit: dati operatore, tipo linea, ciclo di vita OTP e avvisi. Pay-per-OTP da $0.02 + costi 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](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/phone-verification-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=9b5c6c6112303ebc60c0f287aafdb996) ## 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](https://docs.didit.me/it/core-technology/phone-verification/warnings-phone-verification.md)). * 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/`](https://docs.didit.me/it/standalone-apis/phone-send) per recapitare il codice e [`POST /v3/phone/check/`](https://docs.didit.me/it/standalone-apis/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. ```json theme={null} { "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](https://docs.didit.me/it/reference/data-models.md#verifica-telefonica). ```typescript theme={null} 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": "" }` (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](https://docs.didit.me/it/core-technology/phone-verification/overview.md#inviare-codici-whatsapp-dal-proprio-numero). È 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](https://docs.didit.me/it/management-api/lists/overview.md). 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`). ```typescript theme={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 ```json theme={null} { "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`. ```json theme={null} { "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](https://docs.didit.me/it/core-technology/phone-verification/overview.md) — comportamento della funzionalità, prezzi, canali supportati. * [Avvisi della Verifica telefonica](https://docs.didit.me/it/core-technology/phone-verification/warnings-phone-verification.md) — tutti i codici di rischio, trigger di rifiuto e azioni configurabili. * [Modelli di dati — verifica telefonica](https://docs.didit.me/it/reference/data-models.md#verifica-telefonica) — schema canonico campo per campo. * [API telefonica autonoma](https://docs.didit.me/it/standalone-apis/phone-send.md) — endpoint `POST /v3/phone/send/` e [`POST /v3/phone/check/`](https://docs.didit.me/it/standalone-apis/phone-check). * [API di gestione — Liste](https://docs.didit.me/it/management-api/lists/overview.md) — gestione della blocklist telefonica che alimenta `matches[]` con `source: list_entry`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.