> ## 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. # Verifica telefonica: API per inviare codice OTP via SMS > Con Didit, POST /v3/phone/send/ invia un codice monouso via SMS. Nuovo tentativo sui numeri bloccati, validità 5 min, nessun minimo mensile. ## Assegna il nome del tuo brand nell'SMS I codici SMS riportano il nome del mittente SMS della tua applicazione, impostato nella Business Console, senza costi aggiuntivi: > 123456 è il tuo codice di verifica per **Acme Bank** Per inviare un codice con un nome diverso, passa `options.sms_sender_name` (da 1 a 30 caratteri: sono ammesse solo lettere, cifre, spazi e i caratteri ' & - !, e non può trattarsi solo di cifre): ```json theme={null} { "phone_number": "+14155552671", "options": { "preferred_channel": "sms", "sms_sender_name": "Acme Bank" } } ``` Un nome che non rispetta queste regole restituisce `400` e nessun codice viene inviato. I codici WhatsApp usano un messaggio fisso e non sono personalizzati con il brand; per inviarli dal nome della tua azienda, collega il tuo numero WhatsApp Business nella Business Console. Vedi [Invia i codici WhatsApp dal tuo numero](https://docs.didit.me/it/core-technology/phone-verification/overview.md#inviare-codici-whatsapp-dal-proprio-numero). Vedi [Messaggi di verifica personalizzati](https://docs.didit.me/it/core-technology/phone-verification/overview.md#messaggi-di-verifica-personalizzati-con-il-brand) per sapere quale nome compare in un codice e il limite giornaliero per i nuovi nomi. ## Gestisci le interruzioni del provider Se il provider telefonico non è disponibile temporaneamente, questo endpoint restituisce `502` con un codice stabile leggibile dalle macchine: ```json theme={null} { "detail": "The phone verification provider is temporarily unavailable.", "code": "phone_provider_unavailable" } ``` Considera questa risposta idonea a un nuovo tentativo. Usa un breve backoff e mostra all'utente un messaggio che informa della temporanea indisponibilità del servizio, invece di chiedergli di modificare un numero di telefono o un codice validi. ## OpenAPI ````yaml it/openapi-25.json POST /v3/phone/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/phone/send/: post: tags: - Standalone APIs summary: Invia codice telefonico description: >- Invia un codice monouso (OTP) a un numero di telefono tramite WhatsApp, SMS o un altro canale supportato, quindi verificalo con [`POST /v3/phone/check/`](/it/standalone-apis/phone-check). **Come si associano invio e verifica.** Lo stato della verifica è associato alla tua applicazione e al `phone_number` in formato E.164 — la chiamata di verifica non richiede `request_id`. Ogni nuovo invio crea una verifica in sospeso valida per **5 minuti**: chiama l'endpoint di verifica con lo stesso numero e con il codice ricevuto dall'utente prima della scadenza dell'intervallo temporale. Chiamando nuovamente l'endpoint di invio per lo stesso numero mentre una verifica è in sospeso, viene reinviato un codice per quella stessa verifica (`status: "Retry"`, stesso `request_id`). In questo modo può essere associato al massimo un nuovo tentativo (due invii totali); un ulteriore invio avvia una nuova verifica con un nuovo `request_id`. L'intervallo di 5 minuti viene calcolato dal primo invio e non viene esteso dai nuovi tentativi. **Canali di consegna.** `options.preferred_channel` seleziona il canale (predefinito: `whatsapp`; sono supportati anche `sms`, `telegram`, `voice`, `rcs`, `viber` e `zalo`). Quando il canale preferito non è disponibile per il paese o il numero di destinazione, la consegna passa automaticamente a SMS — l'invio restituisce comunque `Success`, e il canale effettivamente utilizzato viene riportato nella risposta della verifica (`phone.verification_method` e gli eventi del `lifecycle`). **Personalizzazione del brand.** I codici SMS includono il nome del mittente SMS della tua applicazione, configurato nella Business Console, senza costi aggiuntivi. Passa `options.sms_sender_name` per inviare un codice con un nome diverso, oppure `options.use_white_label_customization: true` per ripiegare sul tuo nome pubblico white label quando non è impostato alcun nome mittente. I codici WhatsApp utilizzano un messaggio fisso; collega il tuo numero WhatsApp Business nella Business Console per inviarli con il nome e il numero della tua azienda, con addebito della sola tariffa Didit. **Stati dell'invio.** `Success` — OTP inviato per una nuova verifica; `Retry` — OTP reinviato per la verifica in sospeso; `Blocked` — il livello antifrode ha rifiutato l'invio (vedi `reason`, ad es. `repeated_attempts`, `suspicious`, `spam`). Un invio `Blocked` finalizza immediatamente la verifica come `Declined` con un avviso di rischio elevato, quindi una successiva verifica restituirà `Expired or Not Found`. **Fatturazione.** Il prezzo dipende dal paese di destinazione e dal canale che consegna effettivamente il messaggio — consulta i [Prezzi della Verifica telefonica](/it/getting-started/phone-verification-pricing). Solo gli invii con esito `Blocked` sono garantiti come gratuiti: qualsiasi altro tentativo di invio non fatturato viene addebitato al momento della finalizzazione o della scadenza della verifica, anche se la consegna non è mai stata confermata o il fornitore del servizio di consegna ha segnalato il messaggio come non recapitabile. I controlli di verifica sono sempre gratuiti. Come misura contro gli abusi, la verifica telefonica rimane disabilitata fino alla prima ricarica della tua organizzazione (`403`). **Persistenza della sessione.** Ogni nuova verifica viene memorizzata come sessione di tipo API: `request_id` è un vero ID sessione che puoi passare a `GET /v3/session/{sessionId}/decision/`, la verifica compare nella Business Console e vengono inviati i webhook `status.updated` man mano che avanza. **Sandbox.** Le chiavi API di sandbox ignorano la consegna e la fatturazione: dopo la validazione della richiesta (un input non valido restituisce comunque `400`), l'endpoint restituisce un payload statico `Success` con un `request_id` casuale; nessun messaggio viene inviato e nulla viene memorizzato. Utilizza il codice `123456` per la verifica in sandbox. **Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{"detail": "You do not have permission to perform this action."}`) — questa API non restituisce mai `401`. **Limiti di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE, oltre a un limite di protezione dagli abusi di 4 tentativi di invio per numero di telefono all'ora; il superamento di uno di questi limiti restituisce `429`. operationId: post_v3phone_send requestBody: required: true content: application/json: schema: type: object properties: phone_number: type: string maxLength: 20 description: >- Numero di telefono del destinatario in formato E.164 — con `+` iniziale e prefisso internazionale (es. `+14155552671`). I numeri vengono validati e normalizzati in E.164; i numeri non analizzabili o non validi restituiscono `400` con un errore nel campo `phone_number`. example: '+14155552671' options: type: object description: >- Opzioni di consegna dell'OTP. Tutti i campi sono facoltativi. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: Numero di cifre nell'OTP. locale: type: string maxLength: 5 pattern: ^[a-z]{2,3}(-[A-Z]{2,3})?$ description: >- Codice lingua BCP-47 utilizzato per localizzare il messaggio di verifica (ad es. `en-US`, `fr`, `es`). I formati non validi restituiscono `400`. example: en-US preferred_channel: type: string enum: - whatsapp - sms - telegram - voice - rcs - viber - zalo default: whatsapp description: >- Canale di consegna preferito. Se il canale non è disponibile per il paese o il numero di destinazione, il messaggio passa automaticamente all'SMS — l'invio segnala comunque `Success`. use_white_label_customization: type: boolean default: false description: >- Quando è `true`, l'invio è white label: se la tua applicazione non ha un nome mittente SMS, l'SMS riporterà invece il tuo nome pubblico white label ("123456 è il tuo codice di verifica per Acme Bank"). Il tuo nome mittente SMS, se impostato, viene utilizzato indipendentemente da questo flag. Si applica ai messaggi SMS, compreso il fallback via SMS da un altro canale; i codici WhatsApp vengono inviati con un messaggio predefinito e non sono personalizzati con il brand. Il valore predefinito è `false`. sms_sender_name: type: string nullable: true maxLength: 30 example: Acme Bank description: >- Il nome riportato nell'SMS di questo codice ("123456 è il tuo codice di verifica per Acme Bank"), al posto del nome mittente SMS della tua applicazione. Gratuito. Da 1 a 30 caratteri: solo lettere, cifre, spazi e ' & - !, non solo cifre, con spazi singoli tra le parole; qualsiasi altro valore restituisce `400` e nessun codice viene inviato. Se omesso, `null` o vuoto, viene utilizzato il nome mittente SMS della tua applicazione. Ogni applicazione può iniziare a utilizzare fino a due nuovi nomi al giorno (UTC); oltre tale limite, il codice viene inviato con il nome della tua applicazione. Si applica ai messaggi SMS, incluso un fallback via SMS da un altro canale; i codici WhatsApp non sono personalizzati con il marchio. pattern: ^$|^(?![\d ]+$)[\p{L}\p{N}'&!-]+( [\p{L}\p{N}'&!-]+)*$ signals: type: object description: >- Segnali opzionali di dispositivo e rete relativi all'utente finale, inoltrati al livello antifrode per migliorare il rilevamento del traffico abusivo o automatizzato. Tutti i campi sono opzionali. properties: ip: type: string description: >- Indirizzo IP del dispositivo dell'utente finale. IPv4 o IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Identificativo univoco del dispositivo dell'utente finale. Android: `ANDROID_ID`; iOS: `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: Piattaforma del dispositivo dell'utente finale. device_model: type: string maxLength: 255 description: Modello del dispositivo dell'utente finale. example: iPhone17,2 os_version: type: string maxLength: 64 description: >- Versione del sistema operativo del dispositivo dell'utente finale. example: 18.0.1 app_version: type: string maxLength: 64 description: Versione della tua applicazione. example: 1.2.34 user_agent: type: string maxLength: 512 description: User agent del browser o dell'app dell'utente finale. example: >- Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1 vendor_data: type: string description: >- Identificatore opzionale controllato dal chiamante (il tuo ID utente interno, un'email, un UUID, ecc.) memorizzato nella sessione e restituito nella risposta di invio, nella risposta di verifica della corrispondenza, nei webhook e nella Business Console. Usalo per correlare il `request_id` di Didit con il record del tuo utente. metadata: type: object nullable: true description: >- Oggetto JSON a struttura libera opzionale memorizzato nella sessione e restituito nella risposta di invio, nella risposta del controllo di corrispondenza, nei webhook e nella Business Console. required: - phone_number examples: WhatsApp (default): summary: OTP a 6 cifre via WhatsApp, con fallback automatico a SMS value: phone_number: '+14155552671' options: preferred_channel: whatsapp locale: en-US vendor_data: user-1234 SMS with custom code length: summary: Forza la consegna via SMS con un codice a 4 cifre value: phone_number: '+34699999999' options: preferred_channel: sms code_size: 4 locale: es With fraud signals: summary: >- Inoltra i segnali del dispositivo per rafforzare lo screening antifrode value: phone_number: '+14155552671' signals: ip: 192.0.2.1 device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: ios device_model: iPhone17,2 os_version: 18.0.1 app_version: 1.2.34 vendor_data: user-1234 responses: '200': description: >- Invio confermato. Ispeziona `status`: `Success` e `Retry` indicano che un codice è in arrivo; `Blocked` indica che il livello antifrode ha rifiutato e la verifica è già finalizzata come `Declined`. `request_id` è l'ID di sessione persistente (stesso ID in caso di `Retry`). content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationSendResponse' examples: Success: summary: OTP inviato per una nuova verifica value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Secondo invio per lo stesso numero entro la finestra di 5 minuti — stesso request_id value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Blocked: summary: >- Rifiuto antifrode — verifica finalizzata come Rifiutata, nessun costo addebitato value: request_id: 0d8af1f4-0c43-46d7-b75c-6e4e22c0a7b3 status: Blocked reason: repeated_attempts vendor_data: user-1234 metadata: null '400': description: >- Errore di validazione. Un input malformato restituisce l'envelope degli errori di campo di DRF (un array di messaggi per ciascun campo interessato, nidificato sotto `options` per gli errori delle opzioni). Un numero valido a livello sintattico ma rifiutato al momento dell'invio (irraggiungibile o con un tipo di linea non idoneo come un codice breve) restituisce invece un envelope `{"detail": ...}`. content: application/json: examples: Invalid phone number (field error): summary: Il numero non è valido in formato E.164 value: phone_number: - Invalid phone number provided. Missing phone number: summary: '`phone_number` non incluso nel corpo' value: phone_number: - This field is required. Invalid options: summary: >- `code_size` fuori intervallo, `locale` non valido, `preferred_channel` sconosciuto value: options: code_size: - Ensure this value is less than or equal to 8. locale: - Ensure this field has no more than 5 characters. preferred_channel: - '"carrier_pigeon" is not a valid choice.' Number rejected at send time: summary: Formato E.164 valido, ma il numero non può ricevere un OTP value: detail: Invalid phone number provided. Ineligible line type: summary: Il tipo di linea non può ricevere OTP (es. short code) value: detail: Invalid phone line type provided. '403': description: >- Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante (`{"detail": ...}`); una chiave errata, revocata o scaduta restituisce `401`. Restituito inoltre prima di qualsiasi invio quando l'organizzazione non ha mai effettuato una ricarica (meccanismo anti-abuso) o quando il suo saldo non è sufficiente a coprire il prezzo di invio della destinazione (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: >- Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata value: detail: You do not have permission to perform this action. Top-up required: summary: >- La verifica telefonica rimane disabilitata fino alla prima ricarica dell'organizzazione value: detail: >- To protect against abuse, phone verification is disabled until your first top-up. Not enough credits: summary: >- Il saldo dell'organizzazione non è sufficiente per coprire il prezzo di invio value: error: You don't have enough credits to perform this request. '429': description: >- Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). Inoltre, a monte si applica un limite anti-abuso di 4 tentativi di verifica per numero di telefono all'ora. La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. Nota: le intestazioni `X-RateLimit-*`/`Retry-After` accompagnano solo l'errore 429 relativo al limite di scrittura di 300/min; l'errore 429 relativo al limite per numero di telefono non include intestazioni del limite di frequenza. content: application/json: examples: Per-number cap: summary: >- Più di 4 tentativi di verifica per lo stesso numero nell'ultima ora value: detail: >- Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number. Write rate limit exceeded: summary: Più di 300 richieste di scrittura nel minuto corrente value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '500': description: >- Errore imprevisto durante la creazione della verifica non riconducibile a un'interruzione nota del fornitore. È sicuro effettuare un nuovo tentativo. content: application/json: examples: Provider error: summary: Impossibile avviare la consegna dell'OTP value: detail: Error creating phone verification schema: type: object properties: detail: type: string '502': description: >- Il provider di verifica telefonica è temporaneamente non disponibile: una risposta 5xx, timeout o errore di connessione persistito dopo i nuovi tentativi integrati. È possibile riprovare in sicurezza; non viene addebitato nulla e non viene consumato alcun tentativo. content: application/json: examples: Provider outage: summary: Il provider non ha risposto alla richiesta di invio value: detail: >- Phone verification is temporarily unavailable. Please try again shortly. code: phone_provider_unavailable schema: type: object properties: detail: type: string code: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/phone/send/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "phone_number": "+14155552671", "options": { "code_size": 6, "preferred_channel": "whatsapp", "locale": "en-US" }, "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.phone.send_code( phone_number="+14155552671", options={ "locale": "en-US", "preferred_channel": "whatsapp", }, vendor_data="user-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.phone.sendCode({ phone_number: "+14155552671", options: { locale: "en-US", preferred_channel: "whatsapp", }, vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.SendCode(ctx, didit.PhoneSendCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tOptions: didit.Some(didit.PhoneSendCodeParamsOptions{\n\t\tLocale: didit.String(\"en-US\"),\n\t\tPreferredChannel: didit.Some(didit.PhoneSendCodeParamsOptionsPreferredChannel(\"whatsapp\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; import me.didit.types.PhoneSendCodeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.phone().sendCode(PhoneSendCodeParams.builder() .phoneNumber("+14155552671") .options(PhoneSendCodeParams.Options.builder() .locale("en-US") .preferredChannel(PhoneSendCodeParams.Options.PreferredChannel.of("whatsapp")) .build()) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- phone->sendCode([ 'phone_number' => '+14155552671', 'options' => [ 'locale' => 'en-US', 'preferred_channel' => 'whatsapp', ], 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.phone.send_code( phone_number: "+14155552671", options: { locale: "en-US", preferred_channel: "whatsapp", }, vendor_data: "user-1234" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Phone.SendCodeAsync(new PhoneSendCodeParams { PhoneNumber = "+14155552671", Options = new PhoneSendCodeParamsOptions { Locale = "en-US", PreferredChannel = new PhoneSendCodeParamsOptionsPreferredChannel("whatsapp"), }, VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: PhoneVerificationSendResponse: type: object properties: request_id: type: string format: uuid description: >- ID sessione della verifica. Un invio `Retry` restituisce lo stesso `request_id` dell'invio originale. Questo id compare nella Business Console, viene restituito nuovamente da un `POST /v3/phone/check/` finalizzato e può essere passato a `GET /v3/session/{sessionId}/decision/`. status: type: string enum: - Success - Retry - Blocked description: >- `Success` — OTP inviato per una nuova verifica. `Retry` — OTP inviato nuovamente per la verifica in sospeso creata da un invio precedente. `Blocked` — il livello antifrode ha rifiutato l'invio; la verifica viene immediatamente finalizzata come `Declined` e non viene addebitato nulla. reason: type: string nullable: true description: >- Il motivo per cui un invio è stato `Blocked` (ad es. `repeated_attempts`, `suspicious`, `spam`). `null` su `Success` e `Retry`. vendor_data: type: string nullable: true description: Eco del `vendor_data` memorizzato nella sessione (dal primo invio). metadata: type: object nullable: true description: Eco dei `metadata` memorizzati nella sessione (dal primo invio). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.