Estrazione dei dati
Un'API di scansione OCR dei documenti d'identità che restituisce campi strutturati, non un blocco di testo.
ShieldID trasforma un documento d'identità governativo con foto in dati strutturati, campo per campo: nome, data di nascita, numero del documento, scadenza, indirizzo e altro, ciascuno con la propria fonte e il proprio esito. Un'API di estrazione dei dati dai documenti e un'API di verifica dei documenti nella stessa sessione.
Che cosa viene restituito
Campi strutturati, dove il documento li riporta effettivamente.
Non tutti i documenti riportano tutti i campi. ShieldID restituisce ciò che il documento contiene e segnala ciò che non contiene.
- Nome completo
- Come stampati e come codificati nel codice a barre o nella MRZ, dove il documento ne è provvisto.
- Data di nascita
- Letto dal lato stampato e verificato incrociando codice a barre e MRZ.
- Numero del documento
- Numero di patente o numero di passaporto, controllato per coerenza interna ove il formato dell'emittente lo consenta.
- Data di scadenza
- Letta dal lato stampato e dal codice a barre o dalla MRZ.
- Indirizzo
- Letto dal lato stampato e dal codice a barre, ove presente; confrontabile con un documento di indirizzo caricato separatamente.
- Sesso
- Letto dove il documento lo stampa o lo codifica.
- Giurisdizione di rilascio
- Identificato dal codice dell'emittente nel codice a barre, quando il documento ne riporta uno riconosciuto, ove disponibile.
Tre fonti, un unico confronto
Codice a barre, MRZ e fronte stampato, letti con intenzione, non mescolati per caso.
Ogni campo è attribuito alla fonte da cui proviene. Quando due fonti non concordano, sul risultato compare una segnalazione, non una media dei due valori.
Codice a barre PDF417
Il retro di una patente di guida o carta d'identità nordamericana viene decodificato in campi AAMVA strutturati. Quando un documento riporta un codice a barre, i relativi campi hanno la priorità rispetto al fronte stampato.
MRZ del passaporto
La zona a lettura ottica viene individuata, letta e convalidata con le formule delle cifre di controllo ICAO integrate nella zona stessa. Un punteggio minimo di validità, verificato rispetto a tale punteggio, stabilisce se un campo letto dall'MRZ sia affidabile: una zona che non supera il proprio checksum non può prevalere su una fonte più pulita.
OCR strutturato e a pagina intera del fronte
Il lato stampato viene letto sfruttando il layout del documento, se riconosciuto, ricorrendo in alternativa all'OCR a pagina intera, in modo che anche un documento non familiare produca campi leggibili.
I conflitti vengono segnalati, non mediati
Un nome o una data di nascita che non coincide tra fronte, codice a barre e MRZ viene riportato come discrepanza nel risultato. Nulla nella pipeline sceglie silenziosamente un vincitore nascondendo il disaccordo.
Convalida del checksum MRZ
Una zona a lettura ottica deve verificare i propri calcoli prima che ci si possa fidare.
La zona a lettura ottica ICAO di un passaporto contiene per progettazione cifre di controllo. ShieldID le convalida prima di considerare affidabile un campo letto dall'MRZ.
Un rilevatore dedicato individua l'MRZ, un lettore estrae i caratteri e il risultato riceve un punteggio di validità in base alle formule di checksum della zona stessa. Solo un campo che supera il punteggio minimo di validità è considerato attendibile con piena priorità; una zona letta male viene trattata di conseguenza, anziché essere trasmessa come se fosse pulita.
Priorità al codice a barre
Quando le fonti si sovrappongono, prevale la più affidabile.
Lo stesso campo può comparire sul codice a barre, nell'MRZ e sul fronte stampato. ShieldID lo risolve con un unico ordine coerente, ogni volta.
- Codice a barre PDF417
- MRZ del passaporto, una volta superato il checksum
- Lettura strutturata del fronte stampato
- OCR a pagina intera come soluzione di riserva
Documenti comprovanti l'indirizzo
Si carica un secondo documento e si ottiene un semplice confronto dell'indirizzo.
Quando una verifica richiede un documento comprovante l'indirizzo, il richiedente carica un documento separato e ShieldID lo legge come legge il documento d'identità.
Il documento comprovante l'indirizzo viene sottoposto a OCR e il suo indirizzo viene confrontato con quello letto dal documento d'identità. Si tratta di un semplice confronto di testo e token, non di un classificatore di documenti separato, ed è eseguito solo quando la sessione lo richiede e un documento è stato effettivamente fornito.
Oscuramento e gestione dei dati personali (PII)
I dati estratti sono protetti allo stesso modo delle immagini.
I campi strutturati sono soggetti agli stessi controlli di privacy che si applicano alle foto dei documenti d'identità.
Data di nascita cifrata a riposo
La data di nascita è archiviata cifrata a riposo; il servizio non si avvia senza la chiave di cifratura.
Immagini eliminate con un timer
Le immagini del documento e del selfie acquisite vengono eliminate automaticamente con un timer breve, sette giorni per impostazione predefinita. Una scansione viene eseguita a intervalli e di nuovo poco dopo ogni riavvio, così che un periodo di inattività non lasci mai un'immagine oltre il giorno in cui doveva essere eliminata.
Oscuramento dei punteggi sul dispositivo
Quando un valore di corrispondenza o di confidenza verrebbe altrimenti mostrato sul telefono del richiedente, ShieldID elimina la percentuale sottostante da quel messaggio prima della visualizzazione, così che un punteggio grezzo non venga mai esposto al di fuori del Suo account.
Il record sopravvive alle immagini
Le immagini seguono una pianificazione. Il fatto che una verifica sia avvenuta, e ciò che ha rilevato, resta nel Suo account — e, per un'integrazione Trust Ledger, come voce verified/failed nell'Activity Ledger (voci del registro per gli account API ShieldID: prossimamente).
Risultato di esempio
Verdetti per campo, nel formato restituito dall'API.
Nomi, numeri e indirizzi riportati di seguito sono inventati per questo esempio. L'insieme dei campi, le fonti e i verdetti rispecchiano il formato reale di un risultato.
| Campo | Valore | Fonte | Verdetto |
|---|---|---|---|
| person.name | "Maria Gonzalez" | barcode | match |
| person.dob | "1991-07-22" | barcode | match |
| person.document_number | "D1234567" | barcode | match |
| person.document_country | "US" | barcode issuer code | match |
| person.address | "1428 Elm St, Sacramento, CA" | barcode | match |
| identity.name_match | PASS | front vs barcode vs requester | PASS |
| checks.document_tamper | "no_indication" | advisory model | advisory, not gating |
// Sample result. Names, numbers and addresses are fictional.
{
"session_id": "ses_9f2c...sample",
"status": "VERIFIED",
"environment": "sandbox",
"person": {
"name": "Maria Gonzalez",
"dob": "1991-07-22",
"document_type": "DRIVERS_LICENCE",
"document_country": "US",
"document_jurisdiction": "CA",
"address": "1428 Elm St, Sacramento, CA"
},
"identity": {
"checks": ["name_match"],
"warnings": [],
"sources": {
"name": "barcode",
"dob": "barcode",
"address": "barcode"
}
},
"checks": {
"document": "PASS",
"identity": "PASS",
"document_tamper": "no_indication"
},
"completed_at": "2026-09-17T14:02:11Z"
}Note di integrazione
Gli stessi campi, ovunque Lei legga il risultato.
I campi strutturati non sono un prodotto separato dalla sessione di verifica. Arrivano come parte dello stesso risultato.
- I campi vengono forniti nel risultato della sessione che Lei recupera tramite l'API una volta completata la verifica.
- Lo stesso risultato viene consegnato al Suo endpoint tramite un webhook firmato al termine della verifica, così non deve effettuare polling per ottenerlo.
- Ogni campo è attribuito alla propria fonte e riporta il proprio esito, sia nel risultato dell'API sia nel payload del webhook.
- Le sessioni sandbox restituiscono la stessa struttura di campi della produzione, così può sviluppare la Sua integrazione prima che venga letto un solo documento reale.
Domande
Risposte dirette sull'estrazione dei dati.
Veda i campi di persona
Esegua una verifica sandbox e legga il risultato strutturato.
Crei una sessione sandbox, scansioni un documento con il Suo telefono e veda ogni campo, la sua fonte e il suo esito nella risposta. Le sessioni sandbox non vengono mai fatturate.