Saltar para o conteúdo principal
POST
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, com cerca 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 fluxo: Disponível no fluxo
  • 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 alpha-3 para este serviço de base de dados.Exemplo: BRA
string
padrão:"bra_unico_idcloud"
obrigatório
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
Consentimento explícito do utilizador final para este serviço.Exemplo: true
string
padrão:"11111111111"
obrigatório
Número de identificação fiscal ou número fiscal.Exemplo: 11111111111
file
obrigatório
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
string
Nome próprio a validar.Exemplo: John
string
Apelido a validar.Exemplo: Doe
string
Nome completo oficial a validar.Exemplo: John Doe
string
Data de nascimento no formato YYYY-MM-DD.Exemplo: 1990-01-01
string
padrão:"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

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

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