Pular para o conteúdo principal
POST
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, que fica em torno de 50%.

Entradas

  • 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

string
padrão:"BRA"
obrigatório
Código de país ISO 3166-1 alfa-3 deste serviço de banco de dados.Exemplo: BRA
string
padrão:"bra_unico_idcloud"
obrigatório
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
Consentimento explícito do usuário final para este serviço.Exemplo: true
string
padrão:"11111111111"
obrigatório
Número de identificação fiscal.Exemplo: 11111111111
file
obrigatório
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
string
Nome a ser validado.Exemplo: John
string
Sobrenome a ser validado.Exemplo: Doe
string
Nome civil completo a ser validado.Exemplo: John Doe
string
Data de nascimento no formato YYYY-MM-DD.Exemplo: 1990-01-01
string
padrão:"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

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 é 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), 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ó:
Depois, crie cada sessão com o valor sob essa chave:
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 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.
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 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. 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 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 e consulte os Códigos de resultado 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 (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

Última modificação em 1 de novembro de 2026