Vai al contenuto principale
POST
Validazione biometrica Unico IDCloud: confronta il selfie dell’utente con il volto registrato per il suo CPF e restituisce se si tratta della stessa persona, di una persona diversa o se il risultato è inconcludente. Didit espone questo servizio tramite POST /v3/database-validation/ per verificare i dati inviati rispetto alla fonte autorevole e ricevere risultati di corrispondenza normalizzati. Formato di input: tax_number accetta il CPF brasiliano (esattamente 11 cifre).

Copertura

  • Copertura: 96%
  • Paese: Brasile
  • ID servizio: bra_unico_idcloud
  • Dominio dei dati: Identità
  • Categoria: BiometricRiskScore
Circa il 96% dei titolari di CPF brasiliani è associato a un record biometrico nel registro di Unico, circa il doppio della copertura della fonte governativa di confronto facciale, Datavalid, che si ferma intorno al 50%.

Input

  • Input obbligatori: tax_number, selfie
  • Input facoltativi: first_name, last_name, full_name, date_of_birth, vendor_data
  • Consenso: obbligatorio
  • Disponibilità nel workflow: disponibile nel workflow
  • Copertura: 96%
  • Prezzo: $0.20 per query riuscita

Parametri del body

string
predefinito:"BRA"
obbligatorio
Codice paese ISO 3166-1 alpha-3 per questo servizio di database.Esempio: BRA
string
predefinito:"bra_unico_idcloud"
obbligatorio
Array contenente questo ID servizio. Specificare il servizio limita la richiesta a questo specifico database.Esempio: bra_unico_idcloud
Consenso esplicito dell’utente finale per questo servizio.Esempio: true
string
predefinito:"11111111111"
obbligatorio
Numero di identificazione fiscale.Esempio: 11111111111
file
obbligatorio
File immagine del selfie da caricare per la validazione biometrica su database. Formati accettati: JPEG, PNG o WebP.Esempio: @./selfie.jpg
string
Nome di battesimo da validare.Esempio: John
string
Cognome da validare.Esempio: Doe
string
Nome completo ufficiale da validare.Esempio: John Doe
string
Data di nascita nel formato YYYY-MM-DD.Esempio: 1990-01-01
string
predefinito:"user-1234"
Il tuo riferimento stabile per questa persona, ad esempio il tuo ID utente interno. Didit lo usa per collegare i controlli indipendenti allo stesso utente finale e ridurre i falsi segnali del rilevamento dei duplicati.Esempio: user-1234

Regole di input e note sulla validazione

  • CPF brasiliano (esattamente 11 cifre)
  • tax_number deve contenere solo cifre; rimuovi spazi, trattini e punteggiatura prima di inviare la richiesta.
  • tax_number deve essere lungo esattamente 11 caratteri.

Come effettuare la chiamata

Dati restituiti

I campi esatti esposti in source_data dipendono da ciò che restituisce il registro. L’esempio generato per bra_unico_idcloud documenta attualmente questa struttura normalizzata:
  • unico_face_match

Prezzi e SLA

BRA - Le query Unico IDCloud (CPF + selfie) vengono fatturate solo quando Didit riceve un risultato conclusivo dalla fonte di validazione.
  • Prezzo per chiamata: $0.20 USD.
  • Fatturazione: per query riuscita. Non ti viene addebitato nulla quando il registro non è raggiungibile, quando mancano campi obbligatori o quando la richiesta viene rifiutata prima di raggiungere la fonte.
  • Latenza: p95 tipico < 2 s.
  • Disponibilità: 99.9% per trimestre lato Didit; la disponibilità della fonte a valle varia per paese e per dataset.

Informazioni su questa fonte

Unico è un IDtech brasiliano che gestisce il più grande registro privato di dati biometrici facciali del Paese. La sua piattaforma IDCloud contiene più di un miliardo di embedding facciali e ne aggiunge circa 35 milioni ogni mese, alimentata dai flussi di onboarding e riautenticazione di oltre 800 aziende brasiliane, tra cui quattro delle cinque banche più grandi. Questa scala produce la copertura indicata sopra: una ricerca per CPF restituisce un record biometrico per circa il 96% degli adulti brasiliani. Didit ha una partnership diretta con Unico, quindi puoi interrogare IDCloud tramite la normale API di Validazione su database, con pagamento per chiamata, senza un contratto separato con Unico, senza volume minimo e senza un processo di onboarding. In che cosa si differenzia dal registro governativo. Didit offre anche Brazil - CPF + face match (Datavalid), che utilizza la fonte ufficiale SERPRO ed è la scelta giusta quando ti serve specificamente il registro governativo come fonte di riferimento. IDCloud è la scelta migliore per tutto il resto, su due aspetti che puoi verificare: copre circa il 96% degli adulti, rispetto a circa il 50% di Datavalid, e confronta il volto con un record biometrico mantenuto dal registro stesso, anziché con un ritratto tratto da un documento fornito dall’utente, quindi resiste sia alla contraffazione dei documenti sia alle frodi con CPF rubato. Costa inoltre meno della metà per interrogazione.

Flusso consigliato per il Brasile

Per la maggior parte dei casi d’uso brasiliani non serve affatto l’acquisizione del documento. L’utente ti fornisce un CPF, e un selfie con verifica di vitalità conferma che è la persona a cui appartiene.
1

Raccogli il CPF

L’unico input testuale è il CPF a 11 cifre: nessuna foto del documento, nessun nome o data di nascita digitati manualmente.Poiché in questo flusso non viene letto alcun documento, Didit non ha da dove ricavare il CPF se non gli indichi la fonte. Invialo nei metadata della sessione quando crei la sessione e mappalo come input tax_number del passaggio Validazione su database. Nella Business Console è la mappatura degli input del passaggio; tramite l’API dei workflow è database_validation_field_sources del nodo:
Poi crea ogni sessione con il valore sotto quella chiave:
Senza la mappatura il passaggio viene comunque eseguito, ma segnala tax_number come mancante e non interroga mai il registro: non viene addebitato nulla e la voce database_validations della sessione riporta il motivo.
2

Acquisisci il selfie con una verifica di vitalità

Aggiungi un passaggio rilevamento della vitalità allo stesso workflow e scegli il metodo in linea con la tua propensione al rischio: Passive Liveness (nessuna azione da parte dell’utente), Flash 3D oppure Azione 3D e Flash (metodi attivi che proiettano pattern di luce; l’ultimo aggiunge un’azione casuale). Impostalo con face_liveness_method (PASSIVE, FLASHING o ACTIVE_3D) nella Business Console oppure tramite l’API dei workflow. Qualunque metodo scegli, Didit visualizza il passaggio di acquisizione e conferma una persona reale e presente: è ciò che impedisce di inviare una foto archiviata o il replay di uno schermo.
3

Valida il CPF e il selfie con Unico IDCloud

All’interno di un flusso di sessione Didit riutilizza automaticamente il selfie di vitalità (non gestisci mai l’immagine) e legge il CPF dalla mappatura sopra. IDCloud verifica quindi se quel volto appartiene alla persona a cui appartiene il CPF. Il passaggio richiede solo questi due input; se invii anche full_name o date_of_birth in metadata e li mappi, vengono passati a Unico come controlli incrociati, ma non sono obbligatori.
Questo flusso basato solo sul CPF si applica alle integrazioni a sessione e a workflow, in cui Didit esegue l’acquisizione e passa il selfie di vitalità a questo servizio per te. Se chiami direttamente POST /v3/database-validation/, selfie è un file di input obbligatorio e fornisci tu l’immagine: vedi panoramica della Validazione su database per entrambe le modalità.
Costo: circa $0.30 per utente verificato con Passive Liveness: $0.20 per la query IDCloud più $0.10 per la verifica di vitalità, oppure circa $0.35 con un metodo attivo, dove la verifica di vitalità costa $0.15. Sono prezzi di listino: lo sconto del tuo piano si applica a ciascuno di essi; vedi prezzi. Soluzione per circa il 4% senza copertura. Quando IDCloud restituisce INCONCLUSIVE, il registro non è riuscito a ricondurre quel CPF a un record biometrico utilizzabile, di solito perché la persona non vi è presente. Trattalo come “nessuna risposta” e non come un controllo fallito, e ripiega sulla Verifica dell’identità completa: acquisizione del documento più confronto facciale con il ritratto del documento. Tutti restano verificabili e paghi la verifica del documento solo per la piccola quota rimanente. Gestione dei casi rifiutati. BIOMETRIC_NO_MATCH significa che il registro ha stabilito in modo esplicito che il volto non appartiene a quel CPF. Trattalo come un esito negativo forte e non come un invito a riprovare: mandare subito l’utente all’acquisizione del documento è esattamente la strada che vuole un impostore, perché il documento è l’artefatto che lui controlla. Tuttavia i falsi negativi genuini accadono, per esempio con un aspetto cambiato, una vecchia foto nel registro o una cattura scadente, quindi inoltra questi casi alla revisione manuale invece di approvarli automaticamente o di bloccare l’utente. BIOMETRIC_IMAGE_UNUSABLE è diverso: il selfie non è stato letto, quindi chiedi un nuovo scatto. Decidi cosa comporta ciascun esito per la sessione con le azioni Partial Match / No Match e consulta Codici di esito per l’elenco completo. Utenti di ritorno. Paghi una ricerca nel registro una sola volta. Dopo che un utente supera questo flusso, il selfie di vitalità viene archiviato in vendor_data, quindi puoi riverificarlo più tardi con Autenticazione biometrica: una verifica di vitalità più un confronto facciale con quel volto archiviato, per $0.10, con la stessa scelta di metodi di vitalità. Nota che questo vale specificamente per gli utenti di ritorno: una sessione di autenticazione biometrica richiede un volto archiviato (o un portrait_image che fornisci) e fallisce alla creazione se l’utente non ha nessuno dei due, quindi i nuovi utenti passano prima dal flusso descritto sopra.

Continua a leggere

Ultima modifica il 7 novembre 2026