> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Verifica identità BRA: API Unico IDCloud (CPF + selfie)

> Verifica su database brasiliano autorevole tramite Didit: BRA - Unico IDCloud (CPF + selfie). A consumo da $0.20, senza contratti né minimi.

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](https://docs.didit.me/it/api-reference/database-validation/brazil/cpf-facial.md), che si ferma intorno al 50%.

## Input

| Campo | Obbligatorio | Esempio |
| - | -: | - |
| `tax_number` | Sì | `11111111111` |
| `selfie` | Sì | `@./selfie.jpg` |
| `first_name` | No | `John` |
| `last_name` | No | `Doe` |
| `full_name` | No | `John Doe` |
| `date_of_birth` | No | `1990-01-01` |
| `vendor_data` | No | `user-1234` |

* **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

**issuing\_state** `string` *required* (default: BRA)

Codice paese ISO 3166-1 alpha-3 per questo servizio di database.

Esempio: `BRA`

**services** `string` *required* (default: bra\_unico\_idcloud)

Array contenente questo ID servizio. Specificare il servizio limita la richiesta a questo specifico database.

Esempio: `bra_unico_idcloud`

**consent** `boolean` *required* (default: true)

Consenso esplicito dell'utente finale per questo servizio.

Esempio: `true`

**tax\_number** `string` *required* (default: 11111111111)

Numero di identificazione fiscale.

Esempio: `11111111111`

**selfie** `file` *required*

File immagine del selfie da caricare per la validazione biometrica su database. Formati accettati: JPEG, PNG o WebP.

Esempio: `@./selfie.jpg`

**first\_name** `string`

Nome di battesimo da validare.

Esempio: `John`

**last\_name** `string`

Cognome da validare.

Esempio: `Doe`

**full\_name** `string`

Nome completo ufficiale da validare.

Esempio: `John Doe`

**date\_of\_birth** `string`

Data di nascita nel formato `YYYY-MM-DD`.

Esempio: `1990-01-01`

**vendor\_data** `string` (default: 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

```bash cURL theme={null}
curl -X POST "https://verification.didit.me/v3/database-validation/" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "issuing_state=BRA" \
  -F "services=bra_unico_idcloud" \
  -F "vendor_data=user-1234" \
  -F "consent=true" \
  -F "tax_number=11111111111" \
  -F "selfie=@./selfie.jpg"
```

```python Python theme={null}
from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.database_validation.validate(
    issuing_state="BRA",
    services=["bra_unico_idcloud"],
    consent=True,
    tax_number="11111111111",
    vendor_data="user-1234",
    selfie=open("selfie.jpg", "rb"),
)
print(result)
```

```javascript Node.js theme={null}
import Didit, { fileFromPath } from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.databaseValidation.validate({
  issuing_state: "BRA",
  services: ["bra_unico_idcloud"],
  consent: true,
  tax_number: "11111111111",
  vendor_data: "user-1234",
  selfie: await fileFromPath("selfie.jpg"),
});
console.log(result);
```

```go Go theme={null}
ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{
	IssuingState: "BRA",
	Services:     didit.Some([]string{"bra_unico_idcloud"}),
	Consent:      didit.Bool(true),
	TaxNumber:    didit.String("11111111111"),
	VendorData:   didit.String("user-1234"),
	Selfie:       didit.Some(didit.FileFromPath("selfie.jpg")),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)
```

```java Java theme={null}
import java.nio.file.Path;
import java.util.List;
import me.didit.Didit;
import me.didit.types.DatabaseValidationValidateParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder()
        .issuingState("BRA")
        .services(List.of("bra_unico_idcloud"))
        .consent(true)
        .taxNumber("11111111111")
        .vendorData("user-1234")
        .selfie(Path.of("selfie.jpg"))
        .build());
System.out.println(result);
```

```php PHP theme={null}
<?php

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\File;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->databaseValidation->validate([
    'issuing_state' => 'BRA',
    'services' => ['bra_unico_idcloud'],
    'consent' => true,
    'tax_number' => '11111111111',
    'vendor_data' => 'user-1234',
    'selfie' => File::fromPath('selfie.jpg'),
]);
print_r($result->toArray());
```

```ruby Ruby theme={null}
require "didit"

# Reads DIDIT_API_KEY.
didit = Didit::Client.new

result = didit.database_validation.validate(
  issuing_state: "BRA",
  services: ["bra_unico_idcloud"],
  consent: true,
  tax_number: "11111111111",
  vendor_data: "user-1234",
  selfie: Pathname("selfie.jpg")
)
puts result.to_h
```

```csharp .NET theme={null}
using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams
{
    IssuingState = "BRA",
    Services = new string[] { "bra_unico_idcloud" },
    Consent = true,
    TaxNumber = "11111111111",
    VendorData = "user-1234",
    Selfie = FileUpload.FromPath("selfie.jpg"),
});
Console.WriteLine(JsonSerializer.Serialize(result));
```

Ogni chiamata riuscita restituisce HTTP `200`. Il campo **`outcome_code`** indica cosa è successo effettivamente, distinguendo ad esempio una vera mancata corrispondenza biometrica (`BIOMETRIC_NO_MATCH`) da un selfie che non può essere letto (`BIOMETRIC_IMAGE_UNUSABLE`). Lo `status` mostrato è lo stato predefinito della funzionalità; le [azioni Partial Match / No Match configurate](https://docs.didit.me/it/core-technology/database-validation/database-validation-warnings.md) possono sostituirlo.

**`MATCH`** — Il registro ha confermato l'identità e tutti i campi verificati corrispondevano.

```json 200 OK — MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Approved",
  "issuing_state": "BRA",
  "match_type": "full_match",
  "validations": [
    {
      "outcome_code": "MATCH",
      "service_id": "bra_unico_idcloud",
      "service_name": "BRA - Unico IDCloud (CPF + selfie)",
      "source_data": {
        "unico_face_match": "yes"
      },
      "validation": {
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`BIOMETRIC_NO_MATCH`** — Il punteggio di corrispondenza facciale era sotto la soglia di accettazione, quindi il selfie non corrisponde alla foto nel registro.

```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Declined",
  "issuing_state": "BRA",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "BIOMETRIC_NO_MATCH",
      "service_id": "bra_unico_idcloud",
      "service_name": "BRA - Unico IDCloud (CPF + selfie)",
      "source_data": {
        "identification_number": "NO_MATCH"
      },
      "validation": {
        "identification_number": "no_match"
      }
    }
  ]
}
```

**`INCONCLUSIVE`** — Il registro non è in grado di determinare se la persona corrisponde a quella nella foto: il risultato è realmente incerto (la persona potrebbe o non potrebbe essere nel registro). NON è una mancata corrispondenza e NON è un problema tecnico dell'immagine; non viene dichiarato alcun campo, quindi match\_type è null e il controllo viene inviato a revisione.

```json 200 OK — INCONCLUSIVE theme={null}
{
  "request_id": "req_01H…",
  "status": "In Review",
  "issuing_state": "BRA",
  "match_type": null,
  "validations": [
    {
      "outcome_code": "INCONCLUSIVE",
      "service_id": "bra_unico_idcloud",
      "service_name": "BRA - Unico IDCloud (CPF + selfie)",
      "source_data": {},
      "validation": {}
    }
  ]
}
```

## 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](https://unico.io) è 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)](https://docs.didit.me/it/api-reference/database-validation/brazil/cpf-facial.md), 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:

```json theme={null}
{
  "database_validation_countries": {"BRA": {"services": ["bra_unico_idcloud"]}},
  "database_validation_field_sources": {
    "tax_number": {"source": "expected_data", "key": "metadata.cpf"}
  }
}
```

Poi crea ogni sessione con il valore sotto quella chiave:

```json theme={null}
{"workflow_id": "<workflow_id>", "metadata": {"cpf": "12345678909"}}
```

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à](https://docs.didit.me/it/core-technology/liveness/overview.md) 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.

> [!NOTE]
>
> 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](https://docs.didit.me/it/core-technology/database-validation/overview.md) 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](https://docs.didit.me/it/getting-started/pricing.md).

**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à](https://docs.didit.me/it/core-technology/id-verification/overview.md) 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](https://docs.didit.me/it/core-technology/database-validation/database-validation-warnings.md) e consulta [Codici di esito](https://docs.didit.me/it/core-technology/database-validation/database-validation-outcome-codes.md) 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](https://docs.didit.me/it/core-technology/biometric-auth/overview.md): 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

* [Panoramica della Validazione su database per il Brasile](https://docs.didit.me/api-reference/database-validation/brazil.md)
* [Panoramica della Validazione su database](https://docs.didit.me/it/core-technology/database-validation/overview.md)
* [Codici di esito](https://docs.didit.me/it/core-technology/database-validation/database-validation-outcome-codes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.