> ## 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) > Validação na base de dados brasileira via Didit: consulta oficial do CPF com selfie. Por chamada a partir de $0.20, sem contratos nem mínimos. Validação biométrica da Unico IDCloud: compara a selfie do utilizador com a face registada associada ao seu CPF e devolve se é a mesma pessoa, se não é a mesma pessoa ou se o resultado é inconclusivo. A Didit disponibiliza este serviço através de `POST /v3/database-validation/` para que possa verificar os dados submetidos contra a fonte oficial e receber resultados de correspondência normalizados. Formato de entrada: `tax_number` aceita o CPF brasileiro (exatamente 11 dígitos). ## 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 brasileiro têm correspondência num registo biométrico da Unico — cerca do dobro do alcance da fonte governamental de correspondência facial, [Datavalid](https://docs.didit.me/pt/api-reference/database-validation/brazil/cpf-facial.md), com cerca 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 fluxo:** Disponível no fluxo * **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 alpha-3 para este serviço de base de dados. Exemplo: `BRA` **services** `string` *required* (default: bra\_unico\_idcloud) Array que contém este ID de serviço. Fixar o serviço mantém o pedido limitado exatamente a esta base de dados. Exemplo: `bra_unico_idcloud` **consent** `boolean` *required* (default: true) Consentimento explícito do utilizador final para este serviço. Exemplo: `true` **tax\_number** `string` *required* (default: 11111111111) Número de identificação fiscal ou número fiscal. Exemplo: `11111111111` **selfie** `file` *required* Ficheiro de imagem da selfie a carregar para a validação biométrica em base de dados. Formatos aceites: JPEG, PNG ou WebP. Exemplo: `@./selfie.jpg` **first\_name** `string` Nome próprio a validar. Exemplo: `John` **last\_name** `string` Apelido a validar. Exemplo: `Doe` **full\_name** `string` Nome completo oficial a validar. 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) A sua referência estável do utilizador para esta pessoa, como o seu ID interno de utilizador. A Didit usa-a para associar verificações independentes ao mesmo utilizador final e reduzir o ruído na deteção de duplicados. Exemplo: `user-1234` ## Regras de entrada e notas de validação * CPF brasileiro (exatamente 11 dígitos) * `tax_number` deve conter apenas dígitos; remova espaços, hífenes e pontuação antes de enviar o pedido. * `tax_number` deve ter exatamente 11 caracteres. ## Como fazer a chamada ```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)); ``` Cada chamada bem-sucedida devolve HTTP `200`. O campo **`outcome_code`** indica o que aconteceu efetivamente, distinguindo, por exemplo, uma incompatibilidade biométrica real (`BIOMETRIC_NO_MATCH`) de uma selfie que não pôde ser lida (`BIOMETRIC_IMAGE_UNUSABLE`). O `status` apresentado é o estado predefinido da funcionalidade; as suas [ações configuradas para Correspondência parcial / Sem correspondência](https://docs.didit.me/pt/core-technology/database-validation/database-validation-warnings.md) podem substituí-lo. **`MATCH`** — O registo confirmou a identidade e todos os campos verificados correspondem. ```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 corresponde à mesma pessoa que a fotografia do registo. ```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 registo não conseguiu determinar se a pessoa corresponde ao registo - o resultado é efetivamente incerto (a pessoa pode ou não estar no registo). Não é um resultado de não correspondência nem um problema técnico da imagem; não é feita qualquer afirmação sobre os campos, por isso 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 devolvidos Os campos exatos apresentados em `source_data` dependem do que o registo devolve. O exemplo gerado para `bra_unico_idcloud` documenta atualmente esta estrutura normalizada: * `unico_face_match` ## Preços e SLAs As consultas BRA - Unico IDCloud (CPF + selfie) só são faturadas quando a Didit recebe um resultado conclusivo da fonte de validação. * **Preço por chamada:** \$0.20 USD. * **Faturação:** por consulta bem-sucedida. Não é cobrado quando o registo está inacessível, quando faltam campos obrigatórios ou quando o pedido é rejeitado antes de chegar à fonte. * **Latência:** p95 típico \< 2 s. * **Disponibilidade:** 99.9% por trimestre do lado da Didit; a disponibilidade da fonte a jusante varia conforme o país e o conjunto de dados. ## Sobre esta fonte [Unico](https://unico.io) é uma IDtech brasileira que gere o maior registo biométrico facial privado do país. A sua plataforma IDCloud armazena mais de mil milhões de embeddings faciais e acrescenta cerca de 35 milhões de novas faces por mês, alimentada pelos fluxos de onboarding e de reautenticação de mais de 800 empresas brasileiras, incluindo quatro dos cinco maiores bancos. Esta escala é o que produz a percentagem de cobertura indicada acima: uma consulta por CPF permite encontrar um registo biométrico em cerca de 96% dos adultos brasileiros. A Didit tem uma parceria direta com a Unico, pelo que pode consultar a IDCloud através da API padrão de Validação de base de dados, com pagamento por chamada, sem contrato separado com a Unico, sem volume mínimo e sem processo de onboarding. **Em que se distingue do registo governamental.** A Didit também oferece a [Brazil - CPF + face match (Datavalid)](https://docs.didit.me/pt/api-reference/database-validation/brazil/cpf-facial.md), que utiliza a fonte oficial da SERPRO e é a escolha certa quando precisa especificamente do registo governamental como fonte de referência. A IDCloud é a melhor opção para tudo o resto, em dois aspetos que pode verificar: chega a cerca de 96% dos adultos, em comparação com os cerca de 50% alcançados pelo Datavalid, e compara com um registo biométrico mantido pelo próprio registo, e não com uma fotografia retirada de um documento apresentado pelo utilizador, pelo que resiste tanto à falsificação de documentos como à fraude com CPF roubado. Além disso, custa menos de metade por consulta. ## Fluxo recomendado para o Brasil Para a maioria dos casos de uso no Brasil, não precisa de captura de documento. O utilizador fornece o CPF, e uma selfie com verificação de prova de vida confirma que é a pessoa a quem o CPF pertence. **1. Recolha o CPF** A sua única entrada de texto é o CPF de 11 dígitos: não há foto de documento, nem nome ou data de nascimento digitados manualmente. Como neste fluxo nenhum documento é lido, a Didit não tem de onde obter o CPF, a menos que indique a origem. Envie-o em `metadata` da sessão ao criá-la e mapeie-o como o campo `tax_number` do passo de Validação de base de dados. Na Business Console, isto faz-se no mapeamento de inputs do passo; através da API de fluxos, é em `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, o passo continua a ser executado, mas reporta `tax_number` como em falta e nunca consulta o registo. Nada é faturado, e a entrada `database_validations` da sessão indica o motivo. **2. Capture a selfie com verificação de prova de vida** Adicione um passo de [prova de vida](https://docs.didit.me/pt/core-technology/liveness/overview.md) ao mesmo fluxo e escolha o método que corresponde ao seu apetite ao risco: **Prova de vida passiva** (sem qualquer ação do utilizador), **Flash 3D** ou **Ação 3D e Flash** (métodos ativos que projetam padrões de luz, sendo que o último acrescenta uma ação aleatória). Defina-o com `face_liveness_method` (`PASSIVE`, `FLASHING` ou `ACTIVE_3D`) na Business Console ou através da API de fluxos. Qualquer que seja a escolha, a Didit apresenta o passo de captura e confirma uma pessoa real e presente. É isto que impede que uma fotografia guardada ou a reprodução de um ecrã seja submetida. **3. Valide o CPF e a selfie no IDCloud da Unico** Dentro de um fluxo de sessão, a Didit reutiliza automaticamente a selfie da prova de vida, e você nunca manipula a imagem. O CPF é lido a partir do mapeamento acima. O IDCloud confirma então se essa face pertence à pessoa a quem o CPF pertence. O passo precisa apenas destes dois campos. Se também enviar `full_name` ou `date_of_birth` em `metadata` e os mapear, são transmitidos à Unico como verificações cruzadas, mas não são obrigatórios. > [!NOTE] > > Este fluxo apenas com CPF aplica-se às integrações de **sessão e fluxo**, em que a Didit faz a captura e transmite a selfie da prova de vida a este serviço por si. Se chamar **diretamente** `POST /v3/database-validation/`, `selfie` é um campo de ficheiro obrigatório, e é você que fornece a imagem. Consulte a [visão geral da Validação de base de dados](https://docs.didit.me/pt/core-technology/database-validation/overview.md) para os dois modos. **Custo:** cerca de \$0.30 por utilizador 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. Estes são os preços de tabela: o desconto do seu plano aplica-se a cada um deles. Consulte [preços](https://docs.didit.me/pt/getting-started/pricing.md). **Alternativa para os cerca de 4% sem cobertura.** Quando o IDCloud devolve `INCONCLUSIVE`, o registo não conseguiu associar esse CPF a um registo biométrico utilizável, normalmente porque a pessoa não consta dele. Trate isto como "sem resposta" e não como uma verificação falhada, e recorra à [Verificação de identidade](https://docs.didit.me/pt/core-technology/id-verification/overview.md) completa: captura de documento mais correspondência facial com o retrato do documento. Todos continuam a poder ser verificados, e só paga a verificação de documento na pequena parte restante. **Tratamento das recusas.** `BIOMETRIC_NO_MATCH` significa que o registo indicou explicitamente uma não correspondência: a face não pertence a esse CPF. Trate-o como um resultado fortemente negativo e não como um convite a repetir a tentativa. Encaminhar o utilizador diretamente para a captura de documento é precisamente o caminho que um impostor pretende, porque o documento é o artefacto que ele controla. No entanto, existem falsos negativos genuínos: uma aparência alterada, uma fotografia antiga no registo ou uma captura de má qualidade. Por isso, encaminhe estes casos para revisão manual, em vez de aprovar automaticamente ou de deixar o utilizador sem saída. `BIOMETRIC_IMAGE_UNUSABLE` é diferente: a selfie simplesmente não pôde ser lida, pelo que deve pedir uma nova. Defina o efeito de cada resultado na sessão com as [ações de Partial Match / No Match](https://docs.didit.me/pt/core-technology/database-validation/database-validation-warnings.md), e consulte os [Códigos de resultado](https://docs.didit.me/pt/core-technology/database-validation/database-validation-outcome-codes.md) para a lista completa. **Utilizadores recorrentes.** Só precisa de pagar uma consulta ao registo uma vez. Depois de um utilizador passar este fluxo, a selfie da prova de vida fica guardada em `vendor_data` dele, pelo que pode voltar a verificá-lo mais tarde com a [Autenticação biométrica](https://docs.didit.me/pt/core-technology/biometric-auth/overview.md): uma prova de vida mais uma correspondência facial com essa face guardada, por \$0.10, com a mesma escolha de métodos de prova de vida. Note que isto se destina especificamente a utilizadores **recorrentes**: uma sessão de autenticação biométrica precisa de uma face guardada (ou de um `portrait_image` que forneça) e falha na criação se o utilizador não tiver nenhuma das duas. Por isso, os utilizadores pela primeira vez passam sempre pelo fluxo acima. ## Continuar a ler * [Visão geral da Validação de base de dados no Brasil](https://docs.didit.me/api-reference/database-validation/brazil.md) * [Visão geral da Validação de base de dados](https://docs.didit.me/pt/core-technology/database-validation/overview.md) * [Códigos de resultado](https://docs.didit.me/pt/core-technology/database-validation/database-validation-outcome-codes.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.