Vi manca un Paese o un controllo su misura? Diteci di cosa avete bisogno.Prenotate una chiamata di 15 minuti

Integrare la verifica dell'identità in una web app: guida a partire dalla sandbox

Come collegare la verifica dell'identità o dell'età a una web app, dalla prima sessione in sandbox ai webhook e ai risultati firmati, e gli errori in cui è facile cadere lungo il percorso.

7 min di letturanovembre 2026

Di secuveri teamPubblicato il

Una sviluppatrice integra la verifica dell'identità in un'applicazione web

In breve

Il codice per verificare un'identità in una web app è poco. Il vostro server crea una sessione, la persona completa un processo ospitato e il vostro server legge il risultato. La maggior parte dei bug di integrazione nasce dalle decisioni attorno a quel codice: di quale segnale fidarsi, che cosa succede quando una richiesta viene ripetuta e che cosa fa l'app mentre un caso attende una verifica manuale.

Questa guida segue l'integrazione nell'ordine in cui la costruireste, con l'API di secuveri e le app di esempio open source. Se volete prima vedere il risultato finito, provate la demo bancaria o la demo del negozio 18+. Entrambe girano in sandbox.

Come si incastrano i pezzi

Le parti sono tre:

  1. Il vostro backend crea una sessione per una persona e un workflow. Un workflow è l'insieme dei controlli che avete configurato, per esempio documento d'identità, rilevazione della vitalità e confronto del volto, oppure un'età minima.
  2. La persona completa il processo su una pagina ospitata o in un frame incorporato nella vostra app. Al computer il processo mostra un codice QR, così può proseguire sul telefono, dove ci sono la fotocamera e l'NFC.
  3. Il vostro backend riceve l'esito, tramite un webhook firmato e un risultato firmato che recupera dall'API.

Il browser entra in gioco solo nel passo 2. È una scelta voluta e condiziona il resto dell'integrazione.

Partire dalla sandbox

Create una chiave API sandbox nella dashboard, in Settings, API keys. Le chiavi sandbox iniziano con sk_test_, quelle di produzione con sk_live_. Entrambe devono restare soltanto sul vostro server.

Poi create e pubblicate un workflow sandbox con i controlli che vi servono. Se incorporate il processo nella vostra pagina, aggiungete la vostra origine locale, per esempio http://localhost:3030, in Settings, Branding, nell'elenco dei siti autorizzati a incorporare il processo.

La sandbox esegue i controlli reali, quindi durante lo sviluppo potete verificarvi con il vostro documento. Offre inoltre scenari gratuiti che chiudono subito una sessione con l'esito che scegliete, approvato, rifiutato o inviato a verifica, senza documento. Usateli per testare i vostri percorsi di codice. I casi di rifiuto e di verifica manuale li vorrete ripetere molte più volte di quanto chiunque abbia voglia di farsi un selfie.

Creare la sessione sul server

Una sessione è una sola chiamata API: POST /v1/sessions con la vostra chiave API nell'header x-api-key, l'ID del workflow e il vostro riferimento in vendor_data. La risposta contiene un ID di verifica e il link al processo. Con il pacchetto Node.js @secuveri/node la stessa chiamata si chiama createSession.

Due dettagli vi risparmiano problemi più avanti:

  • Mettete il vostro ID in vendor_data. Usate l'ID del conto o dell'ordine a cui appartiene la verifica. Lo controllerete di nuovo quando arriva il risultato.
  • Inviate una Idempotency-Key. Ricavatela dallo stesso ID, per esempio quello dell'ordine. Se la richiesta viene ripetuta dopo un timeout, riceverete la stessa sessione invece di una seconda.

Al browser restituite solo il link o il token della sessione. La chiave API non lascia mai il vostro server.

Aprire il processo

Potete reindirizzare la persona al link, mostrarlo come codice QR o farlo inviare da secuveri via e-mail o SMS. Per tenere le persone dentro la vostra app, usate il pacchetto per browser @secuveri/web e chiamate Secuveri.start con l'URL della sessione. Apre il processo in una finestra modale o in un frame incorporato e comunica l'avanzamento tramite callback come onComplete, onCancel e onError.

Non fidarsi del callback del browser

onComplete significa che la persona è arrivata alla fine del processo. Non significa che l'abbia superato, e chiunque può chiamarlo dalla console per sviluppatori. Trattatelo come un segnale per chiedere l'esito al vostro server, mai come l'esito stesso.

L'esempio del negozio lo mostra bene. Il checkout conferma un ordine solo quando il server ha un risultato approvato proprio per quell'ordine. Chiamare onComplete a mano non cambia nulla, perché il server continua a non trovare alcun risultato approvato.

Gestire bene il webhook

Quando una verifica si conclude o viene esaminata, secuveri invia un webhook all'endpoint impostato in Settings, Webhooks. L'esempio di ricevitore di webhook lo fa in un solo file, seguendo queste regole:

  • Verificare la firma sul corpo grezzo. L'header secuveri-signature è un HMAC-SHA256 calcolato sui byte esatti ricevuti. Se il vostro framework interpreta e riserializza prima il JSON, la firma non corrisponde più.
  • Rispondere in fretta. Restituite uno stato 2xx entro 10 secondi e svolgete dopo il lavoro lento. Qualsiasi altra risposta provoca un nuovo invio, 7 volte nell'arco di circa 21 ore.
  • Eliminare i duplicati tramite l'ID dell'evento. Resta uguale tra un tentativo e l'altro, quindi salvate gli ID già elaborati.
  • Usare il webhook come innesco. Basate la decisione sul risultato firmato, non sul solo contenuto del webhook.

L'endpoint deve essere un URL https pubblico. Nello sviluppo locale usate un tunnel, oppure, fino al deploy, affidatevi al callback del browser seguito da un controllo del risultato lato server.

Leggere e controllare il risultato firmato

Recuperate il risultato con l'ID di verifica (getResult in @secuveri/node). Arriva come risultato firmato: un JWS ES256 che verificate con le chiavi pubbliche pubblicate in /.well-known/jwks.json. Non contiene dati personali, quindi potete conservarlo come prova della decisione senza salvare immagini di documenti o date di nascita.

Prima di agire, controllate:

  • Che riguardi questo caso. vendor_data corrisponde all'ID del vostro conto o ordine e l'ID del workflow è quello atteso. Altrimenti un risultato valido proveniente da un altro workflow, meno esigente, potrebbe essere riutilizzato contro il vostro checkout.
  • Lo stato. COMPLETE con verdetto APPROVED lascia passare la persona. REVIEW_REQUIRED significa che qualcuno del vostro team deve ancora decidere: lasciate il caso in sospeso invece di rifiutarlo. Tutto il resto non è un superamento.
  • I singoli controlli, quando contano. Un negozio con limite di età, per esempio, verifica anche che il controllo dell'età nel risultato rispetti la propria età minima.

Eseguite la stessa logica di chiusura sia dal percorso del browser sia da quello del webhook, e fate in modo che possa girare due volte senza danni. Chi arriva prima chiude il caso, il secondo non trova più nulla da fare.

Testare ciò che può andare storto

Prima di andare live, assicuratevi che la vostra app si comporti in modo sensato quando:

  • la persona chiude il processo a metà;
  • l'esito è un rifiuto, oppure va in verifica manuale e viene approvato il giorno dopo;
  • il webhook arriva prima del callback del browser, o viceversa;
  • lo stesso webhook arriva due volte;
  • la vostra richiesta di sessione va in timeout e viene ripetuta;
  • qualcuno chiama il vostro endpoint di chiusura per un ordine senza verifica.

Gli scenari della sandbox coprono gli esiti. Il resto è il normale test del vostro codice.

Andare in produzione

Il passaggio in produzione è una modifica di configurazione: una chiave sk_live_, un workflow di produzione pubblicato, la vostra origine di produzione nell'elenco dei siti autorizzati e un endpoint per i webhook con il relativo segreto di firma. Il codice resta lo stesso.

Il riferimento completo dell'API, compresi codici di errore e screening AML, si trova nella dashboard all'indirizzo app.secuveri.com/docs, dopo l'accesso. Per una panoramica dell'API consultate la pagina per sviluppatori.

Questo articolo ha scopo informativo e non costituisce consulenza legale o di compliance. I vostri obblighi dipendono dal settore, dall'autorizzazione e dai mercati in cui operate.

secuveri

Costruite un processo di verifica su misura per la vostra azienda.

Continuate a leggere

Contatto

Contattateci

Diteci che cosa volete verificare. Vi mostreremo come secuveri si integra nei vostri processi.

Rispondiamo entro un giorno lavorativo e usiamo i vostri dati solo per la vostra richiesta. Consultate la nostra informativa sulla privacy.