Verifica dell'identità: documento, lookup e wallet

La Verifica dell’identità è un’unica funzionalità con tre metodi. Puoi scegliere quali metodi un paese può utilizzare; l’utente finale riceve quelli applicabili al paese selezionato, e la sessione registra quale metodo ha effettivamente generato il risultato.

Metodo	Cosa fa l’utente	Livello di garanzia
Acquisizione del documento	Fotografa il passaporto, la carta d’identità, la patente di guida o il permesso di soggiorno	Documentale
Ricerca senza documento	Inserisce il proprio numero di identificazione nazionale e alcuni dati personali, verificati rispetto a una fonte governativa o a un’altra fonte autorevole	Corrispondenza dati
Wallet	Accede con un’identità digitale governativa o bancaria come MitID, BankID o itsme	Crittografico

L’acquisizione del documento rimane invariata. Tutto ciò che già configuri tramite documents_allowed — tipi accettati, sottotipi, regole di acquisizione, soglie, avvisi — continua a funzionare esattamente come prima, e un workflow che non specifica nulla sui metodi rimane impostato unicamente sull’acquisizione del documento.

Come funziona ogni metodo

Acquisizione del documento

Ciò che documenta il resto di questa sezione: l’utente fotografa il documento, Didit lo legge, ne verifica l’autenticità e restituisce i campi estratti. Disponibile in tutti i paesi supportati da Didit, a $0.15 per verifica. Inizia dalla panoramica sulla Verifica dell’identità.

Ricerca senza documento

L’utente inserisce il proprio numero di identificazione nazionale e alcuni dati personali, e Didit li verifica rispetto alla fonte autorevole per quel paese. Non è richiesta alcuna fotografia di un documento. Tale fonte è un registro governativo nella maggior parte dei paesi, ma non in tutti: in Canada, Francia, Indonesia, Paesi Bassi, Norvegia, Singapore, Regno Unito e Stati Uniti si tratta invece di un archivio di un’agenzia di informazioni creditizie, di servizi finanziari, di utenze o di registri di residenza. Poiché la provenienza e il regime di consenso applicabile variano di conseguenza, la fonte esatta è indicata per ciascun paese nella tabella seguente e in Ricerca senza documento — senza mai generalizzare. Laddove la fonte restituisce una foto del volto — attualmente Sudafrica, Nigeria, Argentina e Panama, tutti e quattro i registri governativi — all’utente viene richiesto anche un selfie. Su tale selfie viene eseguito il rilevamento passivo della vitalità e viene effettuato il confronto facciale con la foto del registro, il tutto all’interno della ricerca e compreso nel prezzo della ricerca. Laddove la fonte restituisce solo dati, non c’è nulla con cui effettuare il confronto facciale, pertanto non viene scattato alcun selfie; esegui Rilevamento della vitalità e Confronto facciale come passaggi separati del workflow se ne hai bisogno. I campi di richiesta completi per paese, le regole di formato e i regimi di consenso sono disponibili in Ricerca senza documento.

Wallet

L’utente accede con un’identità digitale già in suo possesso, come un’eID nazionale o un’identità bancaria. Il wallet lo autentica e condivide gli attributi di identità firmati con Didit. A seconda del wallet, l’utente può inserire un codice di identificazione personale o un numero di telefono; per il controllo tramite wallet non è necessaria alcuna fotografia del documento. L’esperienza di accesso dipende dal wallet: un reindirizzamento all’app, un codice QR o un codice di confronto confermato sul telefono dell’utente. Smart-ID e Mobile-ID utilizzano un codice di confronto. Gli attributi per singolo wallet, la disponibilità in produzione e la semantica degli errori sono descritti in Wallet di identità digitale.

Livelli di garanzia

Ogni risultato della Verifica dell’identità include un livello di garanzia derivato dal metodo che lo ha prodotto. Il livello è una descrizione accurata di ciò che è stato effettivamente dimostrato, non una graduatoria:

Livello	Valore nella sessione	Cosa significa
Documentale	`documentary`	Un documento fisico è stato acquisito, letto e ne è stata verificata l’autenticità.
Corrispondenza dati	`data_match`	I dati forniti dall’utente corrispondono a un record presente nella fonte interrogata. Nessun documento è stato esaminato.
Crittografico	`cryptographic`	Un provider di identità digitale ha autenticato l’utente e firmato gli attributi condivisi.

I livelli di garanzia sono un’etichetta destinata agli amministratori. Compaiono nel payload della sessione, nella console e nelle esportazioni. Gli utenti finali non vedono mai il livello, il prezzo o il nome della fonte interrogata.

Configurazione dei metodi per paese

I metodi si trovano sotto la chiave methods nella configurazione della funzionalità di Verifica dell’identità (OCR), indicizzati per codice paese ISO 3166-1 alpha-3. Se ometti la chiave, ometti un paese o ometti un metodo all’interno di un paese, quel paese utilizzerà unicamente l’acquisizione del documento.

{
  "feature": "OCR",
  "config": {
    "methods": {
      "ZAF": {
        "document": { "enabled": true },
        "id_lookup": {
          "enabled": true,
          "max_attempts": 2,
          "skip_liveness_and_face_match": true,
          "on_partial_match": "fallback_to_document",
          "on_no_match": "fallback_to_document",
          "on_provider_error": "fallback_to_document"
        },
        "wallet": { "enabled": false, "providers": [], "on_failure": "fallback_to_document" }
      },
      "DNK": {
        "document": { "enabled": true },
        "id_lookup": { "enabled": true, "on_no_match": "decline" }
      }
    }
  }
}

Entrambi i paesi sopra indicati sono available per la ricerca nel catalogo pubblicato. L’esempio lascia i wallet disabilitati, così da non dipendere dall’abilitazione di un wallet nel tuo ambiente. Un workflow che abilita un wallet contrassegnato come Prossimamente viene rifiutato, inclusa l’altra configurazione presente in quel salvataggio. Quando il catalogo contrassegna un wallet come available in un paese, il blocco del wallet per quel paese si presenta così:

{
  "DNK": {
    "document": { "enabled": true },
    "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" }
  }
}

Controlla il catalogo prima di inviarlo. Prerequisito: il wallet deve risultare Disponibile per quel paese, come elencato in Wallet di identità digitale. Due regole applicate dall’API al momento del salvataggio:

La disponibilità è determinata dal server. Un metodo o un wallet che il catalogo delle funzionalità non contrassegna come available per quel paese viene rifiutato. Consulta prima il catalogo — tramite la scheda Paesi della console o con lo strumento MCP didit_workflow_get_id_verification_methods_catalog.
I wallet sono una lista di autorizzazione, mai una graduatoria. providers indica quali wallet un paese può offrire. L’ordine inviato non ha alcun significato e viene normalizzato; la scelta spetta all’utente finale.

La guida di riferimento completa campo per campo, compresi valori predefiniti e convalida, si trova in Configurazioni delle funzionalità del workflow.

Fallback: cosa succede quando un metodo senza documento non va a buon fine

Quattro switch determinano cosa succede dopo. Ciascuno è impostato su fallback_to_document (invia l’utente all’acquisizione del documento) o decline (termina la sessione con una Verifica dell’identità rifiutata); wallet.on_failure accetta anche retry, descritto di seguito. Tutti e quattro hanno come valore predefinito fallback_to_document.

Switch	Si attiva quando
`id_lookup.on_partial_match`	Il registro ha risposto, ma alcuni campi non corrispondevano.
`id_lookup.on_no_match`	Il registro ha risposto e non ha trovato alcun record corrispondente.
`id_lookup.on_provider_error`	Non è stato possibile raggiungere il registro oppure il registro non ha risposto.
`wallet.on_failure`	L’accesso con wallet è stato annullato, è scaduto per timeout o non è riuscito.

wallet.on_failure accetta anche un terzo valore, retry, per un paese che accetta solo il wallet (acquisizione del documento disattivata):

Valore	Un accesso che non si conclude
`fallback_to_document`	Invia l’utente all’acquisizione del documento.
`decline`	Termina la sessione con una Verifica dell’identità rifiutata.
`retry`	Mantiene l’utente nel passaggio del wallet con ” non ha completato l’accesso” e un pulsante principale “Riprova ”. Non viene offerto alcun documento, la sessione non viene mai rifiutata per questo motivo e rimane aperta finché l’utente non termina o fino alla scadenza.

retry è disponibile solo per il wallet: gli switch di lookup accettano fallback_to_document o decline, poiché per un registro che ha risposto “nessuna corrispondenza” non c’è nulla da riprovare. Viene rifiutato se usato insieme a document.fallback_only, che richiede un errore che reindirizzi all’acquisizione del documento. Un wallet che ha effettuato l’accesso e ha restituito dati che non superano i controlli del tuo workflow (età, corrispondenza del nome e così via) costituisce un accesso verificato: la decisione spetta alle regole del workflow, wallet.on_failure non si applica. Un accesso il cui token è autentico ma inaccettabile (livello di affidabilità errato, firma non valida, attestazioni obbligatorie mancanti) viene conteggiato come errore e segue wallet.on_failure. id_lookup.max_attempts (da 1 a 5, valore predefinito 1) indica quanti lookup con risposta sono concessi all’utente prima che lo switch si attivi. Un numero che non supera il controllo del formato lato client non raggiunge mai il registro, quindi non consuma un tentativo: all’utente viene semplicemente richiesto di correggerlo. Un wallet o un lookup possono effettuare il fallback sull’acquisizione del documento solo quando l’acquisizione del documento è abilitata per quel paese ed è accettato almeno un tipo di documento in tale paese. Con l’acquisizione del documento disattivata, o se nessun tipo di documento è accettato per il paese, un accesso non riuscito o un lookup senza corrispondenza rifiuta la sessione, anche se lo switch indica fallback_to_document. L’eccezione è wallet.on_failure: retry, che non rifiuta mai: l’utente rimane nel passaggio del wallet. Non c’è infatti alcuna destinazione di fallback. Quale metodo ha prodotto il risultato: fallback_from verification_method indica sempre il metodo che ha prodotto il risultato verificato: wallet, id_lookup o document. fallback_from spiega il motivo per cui un metodo senza documento non ha concluso il passaggio di verifica dell’identità, in entrambi gli esiti:

Fallback eseguito. L’utente viene inviato all’acquisizione del documento. La verifica del documento che segue presenta verification_method: "document" e fallback_from che indica il metodo non riuscito, ad esempio { "method": "wallet", "reason": "cancelled", "action": "fallback_to_document" }. Una sessione verificata tramite wallet presenta verification_method: "wallet" e fallback_from: null.
Rifiuto. Lo switch è decline, oppure non è disponibile alcun documento su cui effettuare il fallback. La Verifica dell’identità rifiutata presenta fallback_from con "action": "decline".

method è wallet o id_lookup, e reason è l’esito che lo ha concluso (cancelled, timeout, no_match, provider_error e così via). Gli stessi campi arrivano nella decisione della sessione e nel webhook status.updated. Un registro che non risponde (un timeout o un’interruzione del servizio) fa eccezione: non rifiuta mai l’utente di per sé. Il lookup non viene fatturato e non viene utilizzato alcun tentativo; all’utente viene richiesto di riprovare. Dopo tre lookup senza risposta in questo passaggio, si applica id_lookup.on_provider_error: decline rifiuta la sessione, mentre fallback_to_document invia l’utente all’acquisizione del documento. Quando tale switch è fallback_to_document ma il paese non ha alcun documento su cui effettuare il fallback, il lookup rimane aperto e l’utente può continuare a riprovare; la sessione non viene rifiutata.

Offrire l’acquisizione del documento solo come fallback

Per impostazione predefinita, un paese che offre un wallet o un lookup dell’ID insieme all’acquisizione del documento li mostra affiancati nella prima schermata. Imposta document.fallback_only su true per mantenere l’acquisizione del documento abilitata per il paese senza proporla all’inizio. Gli utenti iniziano con il wallet o il lookup dell’ID del paese. Con un unico wallet, l’utente accede direttamente a quel wallet. Solo gli utenti il cui accesso con wallet non riesce, viene annullato o scade per timeout, oppure il cui lookup non trova corrispondenza, vengono indirizzati all’acquisizione del documento. Quali di questi esiti conducano all’acquisizione del documento viene comunque deciso dagli switch sopra indicati, pertanto almeno uno di essi deve essere fallback_to_document.

{
  "FIN": {
    "document": { "enabled": true, "fallback_only": true },
    "wallet": { "enabled": true, "providers": ["ftn"], "on_failure": "fallback_to_document" }
  }
}

fallback_only è facoltativo e ha valore predefinito false. Viene rifiutato a meno che document.enabled non sia true e almeno un wallet o un lookup dell’ID in quel paese effettui il fallback sull’acquisizione del documento. Abilita i tipi di documento che il fallback deve offrire in documents_allowed, ad esempio passaporto e carta d’identità per la Finlandia.

Quanto costa ciascun metodo

Metodo	Prezzo
Acquisizione documento	$0.15 per controllo
Ricerca non documentale	Tariffe pubbliche in USD per paese e identificativo

Questi sono prezzi di listino: lo sconto del tuo piano si applica a entrambi i metodi. Una ricerca utilizza le tariffe al dettaglio pubbliche di Validazione su database per i servizi eseguiti; più servizi possono contribuire a un unico tentativo. La Nigeria seleziona NIN o BVN. La tabella dei paesi mostra il prezzo completo per tentativo configurato, con ogni nuovo tentativo a cui è stata data risposta fatturato separatamente.

Regole di fatturazione

Un registro che ha risposto addebita la ricerca. Corrispondenza, corrispondenza parziale e nessuna corrispondenza contano tutte: la query è stata eseguita e la risposta costituisce il prodotto.
Un registro che non ha mai risposto non viene fatturato. Un errore del provider non costa nulla.
Un numero che non supera il controllo di formato lato client non viene mai fatturato e non viene mai conteggiato rispetto a max_attempts, poiché non ha mai raggiunto il registro.
L’acquisizione del documento viene fatturata in aggiunta quando l’utente ricorre al fallback. Una ricerca che ha risposto e che è poi ricorsa al fallback su un documento genera due addebiti, poiché sono stati eseguiti due controlli.

Copertura

L’acquisizione del documento è disponibile in ogni paese supportato da Didit e non viene ripetuta qui sotto: $0.15 per verifica. Questa tabella elenca solo i paesi in cui esiste un metodo non basato su documenti. Un paese non presente nell’elenco, oppure una cella con la dicitura Non pianificato, supporta solo l’acquisizione del documento.

Paese	Codice	Ricerca non documentale	Wallet di identità digitale
Argentina	`ARG`	Disponibile — RENAPER	Non pianificato
Australia	`AUS`	Non pianificato	ConnectID (prossimamente)
Austria	`AUT`	Non pianificato	EUDI Wallet (prossimamente)
Belgio	`BEL`	Non pianificato	itsme (prossimamente), Smart-ID (disponibile), EUDI Wallet (prossimamente)
Bolivia	`BOL`	Disponibile — SEGIP	Non pianificato
Brasile	`BRA`	Disponibile — Receita Federal	gov.br (prossimamente), Google Wallet (disponibile)
Bulgaria	`BGR`	Non pianificato	EUDI Wallet (prossimamente)
Cambogia	`KHM`	Disponibile — Registro elettorale del Ministero dell’Interno	Non pianificato
Canada	`CAN`	Disponibile — Registri delle agenzie di credito canadesi (doppio processo FINTRAC)	Non pianificato
Cile	`CHL`	Disponibile — Servicio de Registro Civil e Identificación	Non pianificato
Cina	`CHN`	Disponibile — NCIIC (National Citizen Identity Information Center)	Non pianificato
Colombia	`COL`	Disponibile — Registraduría General de la Nación / ANI	Non pianificato
Costa Rica	`CRI`	Disponibile — Tribunal Supremo de Elecciones	Non pianificato
Croazia	`HRV`	Non pianificato	EUDI Wallet (prossimamente)
Cipro	`CYP`	Non pianificato	EUDI Wallet (prossimamente)
Cechia	`CZE`	Non pianificato	Bank iD (prossimamente), MojeID (prossimamente), EUDI Wallet (prossimamente)
Danimarca	`DNK`	Disponibile — Registro CPR	MitID (disponibile), EUDI Wallet (prossimamente)
Repubblica Dominicana	`DOM`	Disponibile — Junta Central Electoral	Non pianificato
Ecuador	`ECU`	Disponibile — Registro Civil del Ecuador	Non pianificato
El Salvador	`SLV`	Disponibile — RNPN	Non pianificato
Estonia	`EST`	Non pianificato	Smart-ID (disponibile), Mobile-ID (disponibile), Carta d’identità estone (prossimamente), EUDI Wallet (prossimamente)
Finlandia	`FIN`	Disponibile — Registro della popolazione DVV	Finnish Trust Network (disponibile), EUDI Wallet (prossimamente)
Francia	`FRA`	Disponibile — Registri residenziali e delle utenze francesi	FranceConnect (prossimamente), EUDI Wallet (prossimamente)
Germania	`DEU`	Non pianificato	Personalausweis (prossimamente), EUDI Wallet (prossimamente)
Grecia	`GRC`	Non pianificato	EUDI Wallet (prossimamente)
Guatemala	`GTM`	Disponibile — RENAP	Non pianificato
Honduras	`HND`	Disponibile — CNE	Non pianificato
Ungheria	`HUN`	Non pianificato	EUDI Wallet (prossimamente)
Islanda	`ISL`	Non pianificato	Auðkenni (in arrivo), EUDI Wallet (in arrivo)
India	`IND`	Disponibile — UIDAI (Aadhaar)	Non pianificato
Indonesia	`IDN`	Disponibile — Registro della popolazione indonesiano tramite registri di residenza	Non pianificato
Irlanda	`IRL`	Non pianificato	EUDI Wallet (in arrivo)
Italia	`ITA`	Non pianificato	EUDI Wallet (in arrivo)
Kenya	`KEN`	Disponibile — IPRS (Integrated Population Registration System)	Non pianificato
Lettonia	`LVA`	Non pianificato	Smart-ID (disponibile), eParaksts mobile (in arrivo), EUDI Wallet (in arrivo)
Liechtenstein	`LIE`	Non pianificato	EUDI Wallet (in arrivo)
Lituania	`LTU`	Non pianificato	Smart-ID (disponibile), Mobile-ID (disponibile), EUDI Wallet (in arrivo)
Lussemburgo	`LUX`	Non pianificato	itsme (in arrivo), EUDI Wallet (in arrivo)
Malesia	`MYS`	Disponibile — JPN (National Registration Department)	Non pianificato
Malta	`MLT`	Non pianificato	EUDI Wallet (in arrivo)
Messico	`MEX`	Disponibile — RENAPO	Non pianificato
Paesi Bassi	`NLD`	Disponibile — Registri di residenza olandesi	itsme (in arrivo), iDIN (disponibile), EUDI Wallet (in arrivo)
Nigeria	`NGA`	Disponibile — NIMC / NIBSS	Non pianificato
Norvegia	`NOR`	Disponibile — Registri di residenza norvegesi	BankID (in arrivo), Vipps (in arrivo), Buypass ID (in arrivo), EUDI Wallet (in arrivo)
Panama	`PAN`	Disponibile — Tribunal Electoral / SIB	Non pianificato
Paraguay	`PRY`	Disponibile — Tribunal Superior de Justicia Electoral	Non pianificato
Perù	`PER`	Disponibile — RENIEC	Non pianificato
Polonia	`POL`	Non pianificato	EUDI Wallet (in arrivo)
Portogallo	`PRT`	Non pianificato	EUDI Wallet (in arrivo)
Romania	`ROU`	Non pianificato	EUDI Wallet (in arrivo)
Singapore	`SGP`	Disponibile — Ufficio di informazioni creditizie e registri delle utenze di Singapore	Google Wallet (disponibile)
Slovacchia	`SVK`	Non pianificato	EUDI Wallet (in arrivo)
Slovenia	`SVN`	Non pianificato	EUDI Wallet (in arrivo)
Sudafrica	`ZAF`	Disponibile — Department of Home Affairs	Non pianificato
Spagna	`ESP`	Non pianificato	EUDI Wallet (in arrivo)
Svezia	`SWE`	Disponibile — Registro della popolazione di Skatteverket	BankID (disponibile), Freja eID (in arrivo), EUDI Wallet (in arrivo)
Taiwan	`TWN`	Non pianificato	Google Wallet (disponibile)
Thailandia	`THA`	Disponibile — Registro dello stato civile DOPA	Non pianificato
Ucraina	`UKR`	Non pianificato	Diia (prossimamente)
Emirati Arabi Uniti	`ARE`	Non pianificato	UAE PASS (prossimamente)
Regno Unito	`GBR`	Disponibile — registri delle agenzie di informazioni creditizie e dei servizi finanziari del Regno Unito	OneID (prossimamente), Google Wallet (disponibile), GOV.UK Wallet (prossimamente)
Stati Uniti	`USA`	Disponibile — registri delle agenzie di informazioni creditizie e dei servizi finanziari degli Stati Uniti	Google Wallet (disponibile)
Uruguay	`URY`	Disponibile — Dirección Nacional del Registro de Estado Civil	Non pianificato
Venezuela	`VEN`	Disponibile — CNE	Non pianificato
Zambia	`ZMB`	Disponibile — Zambia Revenue Authority	Non pianificato

La copertura viene generata dal catalogo delle funzionalità fornito dal backend, pertanto questa tabella è la stessa fonte su cui la console e l’API eseguono la validazione. Prossimamente indica che la voce è visibile nella console ma non può essere ancora attivata; non si tratta di una funzionalità attiva e non comporta alcuna data stabilita.

Cosa include la sessione

Ogni risultato di Verifica dell’identità include il metodo che lo ha prodotto, il suo livello di garanzia e — quando è stato eseguito un metodo non documentale — un blocco di prove specifico per il metodo. Le sessioni basate su documenti rimangono identiche a prima, con le nuove chiavi impostate su null.

Campo	Tipo	Descrizione
`verification_method`	string	`document`, `id_lookup` o `wallet`.
`assurance`	string	`documentary`, `data_match` o `cryptographic`.
`wallet_provider`	string \| null	ID del wallet a catalogo quando il risultato è stato prodotto da un wallet.
`id_lookup`	object \| null	Prove del registro: fonte, orario del controllo, tentativi, confronto campo per campo, foto del soggetto nel registro.
`wallet_verification`	object \| null	Prove della credenziale: fornitore, autorità di emissione, livello di garanzia, validità della firma, attributi condivisi.
`fallback_from`	object \| null	`{ "method": ..., "reason": ..., "action": ... }` quando un metodo non documentale non ha avuto successo: `action` è `fallback_to_document` sulla verifica del documento con cui l’utente ha proseguito, o `decline` sulla Verifica dell’identità rifiutata. `null` se non si è verificato alcun fallback.

I tipi campo per campo e gli esempi per tutti e tre i metodi si trovano nel modello dati di verifica dell’identità, e le stesse chiavi vengono inviate nel webhook status.updated.

Contenuti correlati

Ricerca non documentale — campi specifici per paese, formati, consenso e conservazione
Wallet di ID digitale — attributi specifici del wallet, garanzia e comportamento in caso di fallimento
Metodi di Verifica dell’identità nella console — la scheda Paesi e il tag del metodo di sessione
Configurazioni delle funzionalità del workflow — documentazione di riferimento per la chiave methods

Autenticazione

Verifica

Monitoraggio

Piattaforma

Verifica dell'identità: documento, lookup e wallet

Come funziona ogni metodo

Acquisizione del documento

Ricerca senza documento

Wallet

Livelli di garanzia

Configurazione dei metodi per paese

Fallback: cosa succede quando un metodo senza documento non va a buon fine

Offrire l’acquisizione del documento solo come fallback

Quanto costa ciascun metodo

Regole di fatturazione

Copertura

Cosa include la sessione

Contenuti correlati

​Come funziona ogni metodo

​Acquisizione del documento

​Ricerca senza documento

​Wallet

​Livelli di garanzia

​Configurazione dei metodi per paese

​Fallback: cosa succede quando un metodo senza documento non va a buon fine

​Offrire l’acquisizione del documento solo come fallback

​Quanto costa ciascun metodo

​Regole di fatturazione

​Copertura

​Cosa include la sessione

​Contenuti correlati

Come funziona ogni metodo

Acquisizione del documento

Ricerca senza documento

Wallet

Livelli di garanzia

Configurazione dei metodi per paese

Fallback: cosa succede quando un metodo senza documento non va a buon fine

Offrire l’acquisizione del documento solo come fallback

Quanto costa ciascun metodo

Regole di fatturazione

Copertura

Cosa include la sessione

Contenuti correlati