
Dentro uno stack di verifica moderno
Come controlli su documenti, biometria e segnali di rischio si integrano in una pipeline di verifica in produzione.
5 min · ottobre 2026
Leggi di più: Dentro uno stack di verifica modernoVi manca un Paese o un controllo su misura? Diteci di cosa avete bisogno.Prenotate una chiamata di 15 minuti
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.
Di secuveri teamPubblicato il

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.
Le parti sono tre:
Il browser entra in gioco solo nel passo 2. È una scelta voluta e condiziona il resto dell'integrazione.
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.
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:
Al browser restituite solo il link o il token della sessione. La chiave API non lascia mai il vostro server.
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.
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.
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:
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.
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:
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.
Prima di andare live, assicuratevi che la vostra app si comporti in modo sensato quando:
Gli scenari della sandbox coprono gli esiti. Il resto è il normale test del vostro codice.
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.
Costruite un processo di verifica su misura per la vostra azienda.
Termini correlati

Come controlli su documenti, biometria e segnali di rischio si integrano in una pipeline di verifica in produzione.
5 min · ottobre 2026
Leggi di più: Dentro uno stack di verifica moderno
Che cosa contiene il chip di un passaporto o di una carta d'identità, come uno smartphone lo legge e lo verifica e perché dice più di qualsiasi foto del documento.
Diteci che cosa volete verificare. Vi mostreremo come secuveri si integra nei vostri processi.