> ## 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 verificação BRA - Unico IDCloud (CPF + selfie) > Consulta à base oficial do Brasil via Unico IDCloud (CPF + selfie) com a Didit. A partir de $0.20 por chamada, sem contratos nem mínimos. Validação biométrica Unico IDCloud: compara a selfie do usuário com o rosto registrado para o CPF dele e retorna se é a mesma pessoa, se não é a mesma pessoa ou se o resultado é inconclusivo. A Didit disponibiliza esse serviço por meio de `POST /v3/database-validation/` para que você verifique os dados enviados na fonte oficial e receba resultados de correspondência normalizados. ## Cobertura * **Cobertura:** 96% * **País:** Brasil * **ID do serviço:** `bra_unico_idcloud` * **Domínio de dados:** Identidade * **Categoria:** BiometricRiskScore Cerca de 96% dos titulares de CPF no Brasil têm um registro biométrico na base da Unico. Isso equivale a aproximadamente o dobro do alcance da fonte governamental de correspondência facial, o [Datavalid](https://docs.didit.me/pt-br/api-reference/database-validation/brazil/cpf-facial.md), que fica em torno de 50%. ## Entradas | Campo | Obrigatório | Exemplo | | - | -: | - | | `tax_number` | Sim | `11111111111` | | `selfie` | Sim | `@./selfie.jpg` | | `first_name` | Não | `John` | | `last_name` | Não | `Doe` | | `full_name` | Não | `John Doe` | | `date_of_birth` | Não | `1990-01-01` | | `vendor_data` | Não | `user-1234` | * **Entradas obrigatórias:** `tax_number`, `selfie` * **Entradas opcionais:** `first_name`, `last_name`, `full_name`, `date_of_birth`, `vendor_data` * **Consentimento:** Obrigatório * **Disponibilidade no workflow:** Disponível no workflow * **Cobertura:** 96% * **Preço:** \$0.20 por consulta bem-sucedida ## Parâmetros do corpo **issuing\_state** `string` *required* (default: BRA) Código de país ISO 3166-1 alfa-3 deste serviço de banco de dados. Exemplo: `BRA` **services** `string` *required* (default: bra\_unico\_idcloud) Array que contém o ID deste serviço. Fixar o serviço mantém a requisição restrita exatamente a este banco de dados. Exemplo: `bra_unico_idcloud` **consent** `boolean` *required* (default: true) Consentimento explícito do usuário final para este serviço. Exemplo: `true` **tax\_number** `string` *required* (default: 11111111111) Número de identificação fiscal. Exemplo: `11111111111` **selfie** `file` *required* Arquivo de imagem da selfie a ser enviado para a validação no banco de dados biométrico. Formatos aceitos: JPEG, PNG ou WebP. Exemplo: `@./selfie.jpg` **first\_name** `string` Nome a ser validado. Exemplo: `John` **last\_name** `string` Sobrenome a ser validado. Exemplo: `Doe` **full\_name** `string` Nome civil completo a ser validado. Exemplo: `John Doe` **date\_of\_birth** `string` Data de nascimento no formato `YYYY-MM-DD`. Exemplo: `1990-01-01` **vendor\_data** `string` (default: user-1234) Sua referência de usuário estável para esta pessoa, como o ID interno do usuário. A Didit a usa para vincular verificações avulsas ao mesmo usuário final e reduzir ruído na detecção de duplicidades. Exemplo: `user-1234` ## Regras de entrada e observações de validação * CPF brasileiro (exatamente 11 dígitos) * `tax_number` deve conter apenas dígitos; remova espaços, hífens e pontuação antes de enviar a requisição. * `tax_number` deve ter exatamente 11 caracteres. ## Como chamar ```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} 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)); ``` Toda chamada bem-sucedida retorna HTTP `200`. O campo **`outcome_code`** informa o que de fato aconteceu, distinguindo, por exemplo, uma divergência biométrica real (`BIOMETRIC_NO_MATCH`) de uma selfie que não pôde ser lida (`BIOMETRIC_IMAGE_UNUSABLE`). O `status` exibido é o status padrão do recurso; as [ações de Partial Match / No Match](https://docs.didit.me/pt-br/core-technology/database-validation/database-validation-warnings.md) que você configurou podem substituí-lo. **`MATCH`**: o registro confirmou a identidade e todos os campos verificados corresponderam. ```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`**: a pontuação de correspondência facial ficou abaixo do limiar de aceitação; a selfie não é da mesma pessoa da foto do 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`**: o registro não conseguiu determinar se a pessoa corresponde; o resultado é de fato incerto (ela pode ou não estar no registro). Isso NÃO é uma divergência e NÃO é um problema técnico de imagem; nenhum campo é confirmado, então match\_type é null e a verificação é enviada para revisão. ```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": {} } ] } ``` ## Dados retornados Os campos exatos exibidos em `source_data` dependem do que o registro retorna. O exemplo gerado para `bra_unico_idcloud` documenta atualmente este formato normalizado: * `unico_face_match` ## Preços e SLAs As consultas BRA - Unico IDCloud (CPF + selfie) são cobradas somente quando a Didit recebe um resultado conclusivo da fonte de validação. * **Preço por chamada:** \$0.20 USD. * **Faturamento:** por consulta bem-sucedida. Você não é cobrado quando o serviço de registro está indisponível, quando faltam campos obrigatórios ou quando a requisição é rejeitada antes de chegar à fonte. * **Latência:** p95 típico \< 2 s. * **Disponibilidade:** 99.9% por trimestre do lado da Didit; a disponibilidade da fonte externa varia conforme o país e o conjunto de dados. ## Sobre esta fonte A [Unico](https://unico.io) é uma IDtech brasileira que mantém o maior registro biométrico facial privado do país. Sua plataforma IDCloud reúne mais de um bilhão de embeddings faciais e adiciona cerca de 35 milhões de novos rostos por mês, alimentada pelos fluxos de onboarding e reautenticação de mais de 800 empresas brasileiras, incluindo quatro dos cinco maiores bancos. É essa escala que gera o índice de cobertura acima: uma consulta por CPF encontra um registro biométrico para cerca de 96% dos adultos brasileiros. A Didit tem uma parceria direta com a Unico, então você pode consultar o IDCloud pela API padrão de Validação de banco de dados, pagando por chamada, sem contrato separado com a Unico, sem volume mínimo e sem processo de onboarding. **Como esta fonte difere do registro governamental.** A Didit também oferece [Brasil - CPF + correspondência facial (Datavalid)](https://docs.didit.me/pt-br/api-reference/database-validation/brazil/cpf-facial.md), que é a fonte oficial do SERPRO e a escolha certa quando você precisa especificamente do registro governamental como fonte de verdade. O IDCloud é a melhor escolha para todo o resto, em dois aspectos que você pode verificar: ele alcança cerca de 96% dos adultos, contra aproximadamente 50% do Datavalid, e faz a correspondência com um registro biométrico mantido pelo próprio IDCloud, e não com um retrato extraído de um documento que o usuário fornece. Por isso, resiste tanto à falsificação de documentos quanto à fraude com CPF roubado. Além disso, custa menos da metade do preço por consulta. ## Fluxo recomendado para o Brasil Na maioria dos casos de uso no Brasil, você não precisa de captura de documento. O usuário informa o CPF, e uma selfie validada com prova de vida confirma que ele é a pessoa por trás desse CPF. **1. Colete o CPF** A única entrada de texto é o CPF de 11 dígitos, sem foto de documento e sem nome ou data de nascimento digitados manualmente. Como nenhum documento é lido nesse fluxo, a Didit não tem de onde tirar o CPF, a menos que você indique a origem. Envie-o no `metadata` da sessão ao criá-la e mapeie-o como a entrada `tax_number` da etapa de Validação de banco de dados. No Business Console, isso é o mapeamento de entradas da etapa; pela API de fluxos de verificação (workflows), é o `database_validation_field_sources` do nó: ```json theme={null} { "database_validation_countries": {"BRA": {"services": ["bra_unico_idcloud"]}}, "database_validation_field_sources": { "tax_number": {"source": "expected_data", "key": "metadata.cpf"} } } ``` Depois, crie cada sessão com o valor sob essa chave: ```json theme={null} {"workflow_id": "", "metadata": {"cpf": "12345678909"}} ``` Sem o mapeamento, a etapa ainda é executada, mas informa `tax_number` como ausente e nunca consulta o registro. Nada é cobrado, e a entrada `database_validations` da sessão traz o motivo. **2. Capture a selfie com prova de vida** Adicione uma etapa de [prova de vida](https://docs.didit.me/pt-br/core-technology/liveness/overview.md) ao mesmo fluxo e escolha o método que corresponde ao seu apetite de risco: **Passive Liveness** (nenhuma ação do usuário), **3D Flash** ou **3D Action & Flash** (métodos ativos que projetam padrões de luz, sendo que o último adiciona uma ação aleatória). Configure-o com `face_liveness_method` (`PASSIVE`, `FLASHING` ou `ACTIVE_3D`) no Business Console ou pela API de fluxos. Seja qual for a escolha, a Didit exibe a etapa de captura e confirma que há uma pessoa real e presente. É isso que impede o envio de uma foto armazenada ou de uma reprodução de tela. **3. Valide o CPF e a selfie no Unico IDCloud** Dentro de um fluxo de sessão, a Didit reutiliza automaticamente a selfie da prova de vida (você nunca manipula a imagem) e lê o CPF a partir do mapeamento acima. Em seguida, o IDCloud confirma se esse rosto pertence à pessoa titular do CPF. A etapa precisa apenas dessas duas entradas; se você também enviar `full_name` ou `date_of_birth` no `metadata` e mapeá-los, eles são repassados à Unico como verificações cruzadas, mas não são obrigatórios. > [!NOTE] > > Este fluxo somente com CPF se aplica a integrações por **sessão e fluxo**, em que a Didit faz a captura e repassa a selfie da prova de vida a este serviço em seu nome. Se você chamar `POST /v3/database-validation/` **diretamente**, `selfie` é uma entrada de arquivo obrigatória e você mesmo fornece a imagem. Consulte a [visão geral da Validação de banco de dados](https://docs.didit.me/pt-br/core-technology/database-validation/overview.md) para os dois modos. **Custo:** cerca de \$0.30 por usuário verificado com Prova de vida passiva (\$0.20 pela consulta ao IDCloud mais \$0.10 pela prova de vida) ou cerca de \$0.35 com um método ativo, em que a prova de vida custa \$0.15. Esses são preços de tabela: o desconto do seu plano se aplica a cada um deles; consulte os [preços](https://docs.didit.me/pt-br/getting-started/pricing.md). **Alternativa para os cerca de 4% sem cobertura.** Quando o IDCloud retorna `INCONCLUSIVE`, o registro não conseguiu associar esse CPF a um registro biométrico utilizável, normalmente porque a pessoa não consta nele. Trate isso como "sem resposta", e não como uma verificação reprovada, e recorra à [Verificação de identidade](https://docs.didit.me/pt-br/core-technology/id-verification/overview.md) completa: captura do documento mais correspondência facial com a foto do documento. Todos continuam verificáveis, e você paga pela verificação de documento apenas na pequena parcela restante. **Tratamento de recusas.** `BIOMETRIC_NO_MATCH` significa que o registro apontou uma divergência: o rosto não pertence a esse CPF. Trate isso como um forte indício negativo, e não como um convite para tentar novamente: enviar o usuário direto para a captura de documento é exatamente o caminho que um impostor deseja, já que o documento é o artefato que ele controla. Ainda assim, falsos negativos genuínos acontecem (uma mudança de aparência, uma foto antiga no registro ou uma captura ruim), então encaminhe esses casos para revisão manual em vez de aprovar automaticamente ou encerrar o fluxo para o usuário. `BIOMETRIC_IMAGE_UNUSABLE` é diferente: a selfie simplesmente não pôde ser lida, então peça uma nova. Defina o efeito de cada resultado na sessão com as [ações de correspondência parcial / sem correspondência](https://docs.didit.me/pt-br/core-technology/database-validation/database-validation-warnings.md) e consulte os [Códigos de resultado](https://docs.didit.me/pt-br/core-technology/database-validation/database-validation-outcome-codes.md) para a lista completa. **Usuários recorrentes.** Você só precisa pagar uma vez pela consulta ao registro. Depois que um usuário passa por este fluxo, a selfie da prova de vida fica armazenada vinculada ao `vendor_data` dele, para que você possa reverificá-lo depois com a [Autenticação biométrica](https://docs.didit.me/pt-br/core-technology/biometric-auth/overview.md) (uma prova de vida mais uma correspondência facial com esse rosto armazenado) por \$0.10, com a mesma escolha de métodos de prova de vida. Observe que isso vale especificamente para usuários **recorrentes**: uma sessão de autenticação biométrica precisa de um rosto armazenado (ou de um `portrait_image` fornecido por você) e falha na criação se o usuário não tiver nenhum dos dois, então usuários que usam o serviço pela primeira vez ainda passam pelo fluxo acima. ## Continue a leitura * [Visão geral da Validação de banco de dados no Brasil](https://docs.didit.me/api-reference/database-validation/brazil.md) * [Visão geral da Validação de banco de dados](https://docs.didit.me/pt-br/core-technology/database-validation/overview.md) * [Códigos de resultado](https://docs.didit.me/pt-br/core-technology/database-validation/database-validation-outcome-codes.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.