> ## 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.

# API de verificació Unico IDCloud Brasil (CPF + selfie)

> Consulta a la base de dades oficial del Brasil amb Unico IDCloud (CPF + selfie) via Didit. Des de $0.20 per verificació, sense contractes.

Validació biomètrica d'Unico IDCloud: compara la selfie de l'usuari amb la cara registrada per al seu CPF i retorna si es tracta de la mateixa persona, d'una persona diferent o si el resultat és no concloent. Didit ofereix aquest servei a través de `POST /v3/database-validation/` perquè puguis verificar les dades enviades amb la font de referència i rebre resultats de coincidència normalitzats. Format d'entrada: `tax_number` accepta el CPF brasiler (exactament 11 dígits).

## Cobertura

* **Cobertura:** 96%
* **País:** Brasil
* **ID del servei:** `bra_unico_idcloud`
* **Àmbit de dades:** Identitat
* **Categoria:** BiometricRiskScore

Al voltant del 96% dels titulars de CPF brasilers tenen un registre biomètric al registre d'Unico. Això suposa aproximadament el doble de cobertura que la font oficial de coincidència facial, [Datavalid](https://docs.didit.me/ca/api-reference/database-validation/brazil/cpf-facial.md), que arriba a un 50% aproximadament.

## Entrades

| Camp | Obligatori | Exemple |
| - | -: | - |
| `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` |

* **Entrades obligatòries:** `tax_number`, `selfie`
* **Entrades opcionals:** `first_name`, `last_name`, `full_name`, `date_of_birth`, `vendor_data`
* **Consentiment:** Obligatori
* **Disponibilitat en un flux de treball:** Disponible en un flux de treball
* **Cobertura:** 96%
* **Preu:** \$0.20 per consulta satisfactòria

## Paràmetres del cos

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

Codi de país ISO 3166-1 alfa-3 per a aquest servei de base de dades.

Exemple: `BRA`

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

Matriu que conté l'ID d'aquest servei. Fixar el servei manté la sol·licitud limitada a aquesta base de dades exacta.

Exemple: `bra_unico_idcloud`

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

Consentiment explícit de l'usuari final per a aquest servei.

Exemple: `true`

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

Identificador fiscal o tributari.

Exemple: `11111111111`

**selfie** `file` *required*

Fitxer d'imatge selfie que cal pujar per a la validació biomètrica a la base de dades. Formats acceptats: JPEG, PNG o WebP.

Exemple: `@./selfie.jpg`

**first\_name** `string`

Nom de pila que cal validar.

Exemple: `John`

**last\_name** `string`

Cognom que cal validar.

Exemple: `Doe`

**full\_name** `string`

Nom legal complet que cal validar.

Exemple: `John Doe`

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

Data de naixement en format `YYYY-MM-DD`.

Exemple: `1990-01-01`

**vendor\_data** `string` (default: user-1234)

La teva referència estable d'usuari per a aquesta persona, com ara el teu ID intern d'usuari. Didit l'utilitza per vincular les verificacions independents al mateix usuari final i reduir el soroll de detecció de duplicats.

Exemple: `user-1234`

## Regles d'entrada i notes de validació

* CPF brasiler (exactament 11 dígits)
* `tax_number` ha de contenir només dígits; elimina espais, guions i signes de puntuació abans d'enviar la sol·licitud.
* `tax_number` ha de tenir exactament 11 caràcters.

## Com cridar-lo

```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));
```

Totes les crides satisfactòries retornen HTTP `200`. El camp **`outcome_code`** indica què ha passat realment, i distingeix, per exemple, una discordança biomètrica real (`BIOMETRIC_NO_MATCH`) d'una selfie que no s'ha pogut llegir (`BIOMETRIC_IMAGE_UNUSABLE`). L'`status` que es mostra és l'estat per defecte de la funcionalitat; les [accions de Partial Match / No Match](https://docs.didit.me/ca/core-technology/database-validation/database-validation-warnings.md) que hagis configurat poden substituir-lo.

**`MATCH`**: el registre ha confirmat la identitat i tots els camps comprovats coincideixen.

```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`**: la puntuació de coincidència facial és inferior al llindar d'acceptació; la selfie no correspon a la mateixa persona que la fotografia del registre.

```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`**: el registre no ha pogut determinar si la persona coincideix; el resultat és realment incert (la persona pot estar o no al registre). NO és una discordança ni un problema tècnic amb la imatge; no s'afirma cap camp, per tant match\_type és null i la verificació s'envia a revisió.

```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": {}
    }
  ]
}
```

## Dades retornades

Els camps exactes que apareixen a `source_data` depenen del que retorni el registre. L'exemple generat per a `bra_unico_idcloud` documenta actualment aquesta forma normalitzada:

* `unico_face_match`

## Preus i SLA

Les consultes BRA - Unico IDCloud (CPF + selfie) només es facturen quan Didit rep un resultat concloent de la font de validació.

* **Preu per consulta:** \$0.20 USD.
* **Facturació:** per consulta satisfactòria. No se't cobra quan el registre no és accessible, quan falten camps obligatoris o quan la sol·licitud es rebutja abans d'arribar a la font.
* **Latència:** p95 típic inferior a 2 s.
* **Disponibilitat:** 99.9% per trimestre per part de Didit; la disponibilitat de la font de dades varia segons el país i el conjunt de dades.

## Sobre aquesta font

[Unico](https://unico.io) és una IDtech brasilera que gestiona el registre biomètric facial privat més gran del país. La seva plataforma IDCloud conté més d'un miler de milions d'embeddings facials i en suma uns 35 milions de cares noves cada mes, alimentada pels fluxos d'alta i de reautenticació de més de 800 empreses brasileres, entre elles quatre dels cinc bancs més grans. Aquesta escala és el que explica la xifra de cobertura anterior: una consulta de CPF obté un registre biomètric per a un 96% dels adults brasilers.

Didit té un acord directe amb Unico, de manera que pots consultar IDCloud a través de l'API de Validació en bases de dades estàndard. La facturació és per consulta, sense contracte separat amb Unico, sense volum mínim i sense procés d'alta.

**Com es diferencia del registre governamental.** Didit també ofereix [Brazil - CPF + face match (Datavalid)](https://docs.didit.me/ca/api-reference/database-validation/brazil/cpf-facial.md), que utilitza la font oficial de SERPRO i és l'opció adequada quan necessites específicament el registre governamental com a font de referència. IDCloud és la millor opció per a la resta de casos, en dos aspectes que pots comprovar: arriba a uns 96% dels adults, davant del 50% aproximat de Datavalid, i compara la cara amb un registre biomètric que el mateix registre manté, en lloc d'una fotografia extreta d'un document que l'usuari et proporciona. Per això resisteix tant la falsificació de documents com el frau amb CPF robat. A més, costa menys de la meitat per consulta.

## Flux recomanat per al Brasil

Per a la majoria de casos d'ús al Brasil no cal captura de document. L'usuari et facilita un CPF i un selfie amb prova de vida confirma que és la persona que hi correspon.

**1. Recopila el CPF**

L'única entrada de text és el CPF d'11 dígits: no cal una foto del document, ni un nom ni una data de naixement introduïts manualment.

Com que en aquest flux no es llegeix cap document, Didit no té d'on treure el CPF tret que indiquis d'on prové. Envia'l dins de `metadata` de la sessió en crear-la, i assigna'l a l'entrada `tax_number` del pas de Validació en bases de dades. A la Business Console, això és la configuració de mapatge d'entrades del pas; a través de l'API de fluxos de treball, és `database_validation_field_sources` del node:

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

Després crea cada sessió amb el valor sota aquesta clau:

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

Sense el mapatge, el pas s'executa igualment, però informa que `tax_number` falta i no consulta mai el registre: no es factura res, i l'entrada `database_validations` de la sessió indica el motiu.

**2. Captura el selfie amb una prova de vida**

Afegeix un pas de [prova de vida](https://docs.didit.me/ca/core-technology/liveness/overview.md) al mateix flux de treball i tria el mètode que s'ajusti al teu nivell de risc: **Prova de vida passiva** (sense cap acció de l'usuari), **Flash 3D** o **Acció 3D i Flash** (mètodes actius que projecten patrons de llum; l'últim afegeix una acció aleatòria). Configura-ho amb `face_liveness_method` (`PASSIVE`, `FLASHING` o `ACTIVE_3D`) a la Business Console o a través de l'API de fluxos de treball. Sigui quin sigui el que triïs, Didit mostra el pas de captura i confirma que hi ha una persona real i present: això evita que s'enviï una foto emmagatzemada o la reproducció d'una pantalla.

**3. Valida el CPF i el selfie amb Unico IDCloud**

Dins d'un flux de sessió, Didit reutilitza automàticament el selfie de la prova de vida (mai no gestiones la imatge) i llegeix el CPF del mapatge anterior. IDCloud confirma després si aquesta cara pertany a la persona a qui pertany el CPF. El pas només necessita aquestes dues entrades; si també envies `full_name` o `date_of_birth` dins de `metadata` i els mapeges, es passen a Unico com a verificacions creuades, però no són obligatoris.

> [!NOTE]
>
> Aquest flux només amb CPF s'aplica a les integracions de **sessió i de flux de treball**, en què Didit fa la captura i et passa el selfie de la prova de vida a aquest servei. Si crides **directament** `POST /v3/database-validation/`, `selfie` és un fitxer obligatori i tu n'aportes la imatge; consulta la [visió general de la Validació en bases de dades](https://docs.didit.me/ca/core-technology/database-validation/overview.md) per a les dues modalitats.

**Cost:** aproximadament \$0.30 per usuari verificat amb Prova de vida passiva: \$0.20 per la consulta a IDCloud més \$0.10 per la prova de vida; o aproximadament \$0.35 amb un mètode actiu, on la prova de vida costa \$0.15. Són preus de llista: el descompte del teu pla s'aplica a cadascun; consulta [preus](https://docs.didit.me/ca/getting-started/pricing.md).

**Alternativa per al 4% aproximadament sense cobertura.** Quan IDCloud retorna `INCONCLUSIVE`, el registre no ha pogut vincular aquest CPF amb un registre biomètric utilitzable, típicament perquè la persona no hi és. Tracta-ho com a "sense resposta" i no com a una verificació fallida, i recorre a la [Verificació d'identitat](https://docs.didit.me/ca/core-technology/id-verification/overview.md) completa: captura del document més coincidència facial amb el retrat del document. Tothom continua podent verificar-se, i només pagues la verificació documental per la petita part restant.

**Gestió dels rebuigs.** `BIOMETRIC_NO_MATCH` vol dir que el registre ha discrepat activament: la cara no pertany a aquell CPF. Tracta-ho com un negatiu fort i no com una invitació a tornar-ho a intentar: enviar l'usuari directament a la captura de document és exactament el camí que vol un suplantador, ja que el document és l'artefacte que controla. Tot i això, sí que hi ha falsos negatius genuïns: un canvi d'aspecte, una foto antiga al registre o una captura deficient. Per això, envia'ls a revisió manual en lloc d'aprovar-los automàticament o de deixar l'usuari sense sortida. `BIOMETRIC_IMAGE_UNUSABLE` és diferent: el selfie simplement no s'ha pogut llegir, així que demana'n un de nou. Decideix quin efecte té cada resultat sobre la sessió amb les [accions de Partial Match / No Match](https://docs.didit.me/ca/core-technology/database-validation/database-validation-warnings.md), i consulta [Codis de resultat](https://docs.didit.me/ca/core-technology/database-validation/database-validation-outcome-codes.md) per a la llista completa.

**Usuaris que tornen.** Només cal pagar una consulta al registre una vegada. Després que un usuari superi aquest flux, el selfie de la prova de vida es desa associat al seu `vendor_data`, de manera que pots tornar a verificar-lo més endavant amb [Autenticació biomètrica](https://docs.didit.me/ca/core-technology/biometric-auth/overview.md): una prova de vida més una coincidència facial amb aquesta cara desada, per \$0.10, amb la mateixa elecció de mètodes de prova de vida. Ten en compte que això és només per a usuaris que **tornen**: una sessió d'autenticació biomètrica necessita una cara desada (o un `portrait_image` que aportis) i falla en crear-se si l'usuari no en té cap, de manera que els usuaris nous passen igualment pel flux anterior.

## Continua llegint

* [Visió general de Database Validation al Brasil](https://docs.didit.me/api-reference/database-validation/brazil.md)
* [Visió general de la Validació en bases de dades](https://docs.didit.me/ca/core-technology/database-validation/overview.md)
* [Codis de resultat](https://docs.didit.me/ca/core-technology/database-validation/database-validation-outcome-codes.md)


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