Skip to content

API di verifica dell'età per siti web e app

Verifichi che un visitatore rispetti la soglia di età, senza che la Sua applicazione conservi documenti d'identità o date di nascita.

Controlli che il visitatore rispetti la soglia di età

Una sola sessione fa entrambe le cose: il visitatore dimostra di controllare il proprio numero di telefono tramite WhatsApp, risponde una sola volta alla domanda sull'età e la Sua applicazione riceve il risultato, soglia raggiunta o non raggiunta, rispetto alla soglia da Lei impostata.

Come funziona la verifica dell'età

Primo passaggio, verificare il telefono. Si chiama POST /start-verification con flow=age e si mostra il deep link WhatsApp restituito come codice QR su desktop o come pulsante su dispositivi mobili. Il visitatore invia un messaggio precompilato dal proprio account WhatsApp, così il controllo del numero è dimostrato dall'atto dell'invio e non da un codice che Lei ha spedito a quel numero.

Secondo passaggio, impostare la soglia. La stessa chiamata accetta un min_age facoltativo. Se lo si omette, si applica la soglia configurata sul Suo account, che è 18 salvo modifiche. min_age è accettato solo con flow=age e deve essere un intero positivo; qualsiasi altro valore restituisce un errore 400.

Terzo passaggio, completare il controllo dell'età. Non appena la parte telefonica è dimostrata, la risposta contiene un blocco age con status pending e un age_verification_url. Lo stesso link monouso viene inviato al visitatore su WhatsApp e può essere usato per farlo proseguire nel browser in cui si trova già. Il visitatore risponde presso il provider dell'età, quindi torna al Suo callback_url con token e age=verified, denied o failed in coda.

Quarto passaggio, ricevere il risultato. Un secondo webhook, age_verification_result, parte quando il provider risponde, e GET /check-verification-status riporta lo stesso esito. Il blocco age contiene status, verified, required (la soglia effettivamente controllata), verified_at e provider.

C'è una trappola da conoscere prima di scrivere il ciclo di polling. Lo stato della sessione raggiunge verified non appena il numero di telefono è dimostrato, mentre age.status è ancora pending. Consideri il blocco age come il segnale per il passaggio sull'età, mai lo stato della sessione.

Verifica telefonica + verifica dell'età

I due passaggi rispondono a due domande diverse e il flusso le tiene separate di proposito. Inviare un messaggio WhatsApp dimostra che il visitatore controlla quel numero. Non dice assolutamente nulla sulla sua età: un numero di telefono non è una prova dell'età e nessuna parte di questo flusso lo considera tale.

Ciò che il passaggio telefonico offre è un luogo in cui collocare la risposta. Un risultato sull'età da solo è un fatto slegato: qualcuno, da qualche parte, ha superato una soglia. Legato a un numero che il visitatore ha appena dimostrato di usare, diventa qualcosa che si può riconoscere alla visita successiva.

Questo rende anche economico il visitatore che ritorna. Un risultato positivo viene conservato per un anno rispetto al numero di telefono, quindi chi ha già superato la stessa soglia dimostra di nuovo il numero e porta con sé la risposta precedente, senza essere rimandato al provider. Terminare il messaggio WhatsApp con #reset salta la cache quando serve una risposta aggiornata.

Verificare l'età senza costruire un database di identità

La domanda che pone un controllo dell'età è un booleano. La maggior parte dei dati di solito raccolti per rispondere non lo è, ed è questo che rende un archivio di documenti uno scambio così sfavorevole: si finisce per custodire passaporti e patenti di guida per memorizzare un sì.

Ciò di cui la Sua applicazione ha bisogno è poco. Il risultato: verified, denied, failed oppure ancora pending. La soglia che è stata controllata. Quando è arrivata la risposta e quale provider l'ha fornita. L'identificatore di sessione e il numero di telefono verificato che collegano la risposta al visitatore che si ha davanti. Questo è l'intero blocco age più ciò che il flusso telefonico restituisce già.

Ciò di cui la Sua applicazione non ha bisogno è una data di nascita o un documento d'identità, e l'API non restituisce né l'una né l'altro, quindi non c'è alcun campo da registrare per errore. Una risposta positiva viene conservata rispetto al numero di telefono come risposta, soglia e data. Le credenziali del provider risiedono in segreti lato server e ciò che il provider ha dovuto esaminare per arrivare alla sua decisione non Le viene trasmesso.

Nulla di tutto ciò è una dichiarazione sui Suoi obblighi. Che cosa deve verificare, per quanto tempo deve poter dimostrare di averlo verificato e che cosa costituisca un metodo accettabile sono questioni per il Suo consulente legale e per l'autorità di regolamentazione, non per un fornitore di API.

Verifica dell'età e verifica dell'identità

La verifica dell'età risponde a una sola domanda: questo visitatore rispetta la soglia di età da Lei impostata? La verifica dell'identità risponde a un'altra: chi è questa persona? Le due cose vengono spesso vendute insieme e movimentano quantità di dati molto diverse.

flow=age è del primo tipo. Non restituisce nome, data di nascita né nulla di un documento. Non è KYC, e un risultato positivo non è un'attestazione d'identità su cui fare affidamento altrove. Se il Suo obbligo è sapere chi sia un cliente, questo non è lo strumento adatto a quella parte.

Eredita inoltre l'assunto alla base di ogni controllo telefonico: che il numero appartenga a chi lo usa. Dimostrare il controllo inviando un messaggio è un terreno più solido che ricevere un SMS, ma un adolescente con accesso al telefono di un adulto è uno scenario che nessun controllo a distanza esclude del tutto. L'articolo sui controlli dell'età che non diventano un database di documenti, indicato di seguito, approfondisce l'architettura, i quattro stati e i limiti.

Integri la verifica dell'età nella Sua app

Sono le due chiamate REST che ogni integrazione Phone-Verif utilizza, con un solo parametro modificato. Si autentichi con la Sua chiave API nell'header x-api-key, apra la sessione con flow=age e legga il blocco age dall'endpoint di stato o dal webhook.

  1. Visitatore
  2. Verifica telefonica tramite WhatsApp
  3. Controllo dell'età presso il provider
  4. Risultato sull'età
  5. La Sua applicazione

I due passaggi rispondono a due domande diverse e restano distinti per tutto il flusso. L'invio del messaggio WhatsApp dimostra che il visitatore controlla quel numero; non viene mai considerato una prova della sua età. È il passaggio sull'età a produrre il risultato sull'età.

curl -X POST "https://api.phone-verif.com/start-verification?flow=age&min_age=18" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "checkout-4821", "callback_url": "https://your-app.example/age-checked"}'

Apra una sessione con flow=age. Se omette min_age, si applica la soglia configurata sul Suo account, che è 18 salvo modifiche.

{
  "status": "verified",
  "age": { "status": "pending", "verified": false, "required": 18 },
  "age_verification_url": "https://t.phone-verif.com/av/AbCd1234"
}

La sessione raggiunge verified non appena il numero di telefono è dimostrato, mentre il passaggio sull'età è ancora in sospeso. Per la risposta sull'età legga age.status, non lo stato della sessione, e indirizzi il visitatore a age_verification_url per completare il controllo nel browser in cui si trova già.

{
  "event": "age_verification_result",
  "session_id": "checkout-4821",
  "validation_token": "...",
  "age": {
    "status": "verified",
    "verified": true,
    "required": 18,
    "verified_at": "2026-09-01T22:00:00.000Z",
    "provider": "ageverif"
  }
}

Quando il provider risponde, un secondo webhook trasporta il risultato e l'endpoint di stato riporta lo stesso blocco.

flow=age richiede un provider di verifica dell'età configurato sul Suo account. Se richiesto senza, l'API risponde 503 con il codice age_not_configured, così una configurazione errata si distingue da un'interruzione del servizio.

Domande frequenti sulla verifica dell'età

Posso verificare che gli utenti abbiano più di 18 anni?
Sì. Apra la sessione con flow=age e ometta min_age: il flusso controlla allora la soglia configurata sul Suo account, che è 18 salvo modifiche nelle impostazioni.
Posso usare un'età minima diversa?
Sì. Passi min_age nella chiamata di avvio con la soglia che Le serve. Deve essere un intero positivo, è accettato solo con flow=age e qualsiasi altro valore viene rifiutato con un errore 400. Ogni sessione mantiene la soglia con cui è stata aperta e tale soglia ritorna come required nel blocco age, così chi legge in seguito sa che cosa è stato effettivamente accertato.
Devo memorizzare la data di nascita dell'utente?
No, e non potrebbe nemmeno volendo: l'API non ne restituisce una. Ciò che torna è se la soglia è stata raggiunta, quale fosse la soglia, quando è arrivata la risposta e quale provider l'ha fornita.
Devo conservare documenti d'identità?
No. Il provider può dover vedere un documento per formulare la propria risposta; la Sua applicazione riceve sempre e solo la risposta. L'API non restituisce nulla del documento, quindi non c'è nulla da conservare.
La verifica dell'età dimostra l'identità di una persona?
No. flow=age risponde alla domanda se chi possiede un numero di telefono verificato rispetti una soglia. Non è una verifica dell'identità né KYC: nessun nome, nessuna data di nascita, nessun documento.
Che cosa succede se la verifica dell'età non riesce?
denied e failed sono esiti diversi e non vanno ridotti a uno solo. denied è una decisione del provider, e rieseguire il controllo non cambierà la risposta. failed significa che il provider non è stato raggiungibile, quindi non è stato deciso nulla e un nuovo tentativo è legittimo. Un rifiuto o un errore del provider non viene fatturato; un controllo dell'età completato viene fatturato come seconda unità oltre alla verifica telefonica.
Posso combinare verifica telefonica e verifica dell'età?
È esattamente ciò che è flow=age. Una sola sessione dimostra il numero di telefono tramite WhatsApp e poi esegue il passaggio sull'età, ed entrambi i risultati arrivano su quella stessa sessione. Non servono due integrazioni né la riconciliazione di due identificatori.
Posso forzare un nuovo controllo per un visitatore che ritorna?
Sì. Un risultato positivo viene riutilizzato per un anno rispetto allo stesso numero di telefono e alla stessa soglia. Terminare il messaggio di verifica WhatsApp con #reset salta la risposta in cache e fa ripetere al visitatore l'intero controllo.

Related

Casi d'uso della verifica dell'età

Contenuti per adulti

Dove una casella autodichiarata non viene più considerata un controllo. Il risultato sull'età regola l'accesso prima che venga servito qualsiasi contenuto, e al visitatore non viene chiesto di caricare un documento.

Gioco d'azzardo online

Account di scommesse e casinò che devono tenere fuori i minorenni. Il controllo si inserisce alla registrazione e, se le Sue regole lo richiedono, di nuovo prima di un'azione sensibile.

Alcolici e beni soggetti a limiti di età

Bevande, tabacco, sigarette elettroniche, coltelli, solventi e fuochi d'artificio. Il controllo si colloca prima del checkout, sull'ordine e non sulla sessione di navigazione.

Gaming

Titoli con classificazione per età, funzioni di chat e meccaniche a pagamento limitate al di sotto di una certa età. La soglia è un parametro della richiesta, quindi funzioni diverse possono richiederne di diverse.

Marketplace

Inserzioni limitate per legge o dalla Sua policy. Acquirenti e venditori possono avere soglie diverse aprendo la sessione con un min_age diverso.

Piattaforme social e community

Regole di età minima per account, messaggi diretti o funzioni live. La risposta è legata a un numero di telefono verificato, quindi sopravvive alla fine della sessione.

Build your verifica dell'età flow today

Start integrating in minutes with clear documentation, SDKs, and global message delivery.