API de correspondência facial 1:1: selfie x documento

A Correspondência facial da Didit compara dois rostos 1:1, geralmente a selfie de uma prova de vida com o retrato do documento de identidade do usuário, e retorna uma pontuação de similaridade de 0 a 100. Os limites que você define decidem se a verificação é aprovada; a API independente POST /v3/face-match/ recusa por padrão uma pontuação igual ou inferior a 30. Na lição da Academy sobre como ler o resultado de uma verificação, o capítulo de 6:16 aborda a verificação de correspondência facial dentro de uma sessão real.

​

Novas tentativas e feedback acionável

Em uma sessão da Didit, uma correspondência facial que falha por um motivo de captura corrigível (a selfie está escura demais, desfocada, descentralizada ou a similaridade está no limite) não é recusada de imediato. O usuário é convidado a tentar novamente com orientação, até um número configurável de tentativas - o mesmo modelo usado na Prova de vida.

• Limite de tentativas - face_match_max_attempts controla o número total de envios de correspondência facial por sessão. O padrão é 3 (uma tentativa inicial mais duas novas tentativas), configurável por nó do fluxo (workflow) (intervalo de 1 a 3).
• Feedback de nova tentativa - enquanto restarem tentativas, uma falha que permite nova tentativa mantém o usuário na etapa e retorna feedback_codes (os SDKs Web e Mobile exibem esses códigos automaticamente como mensagens de orientação):
  {
    "detail": "Make sure your face matches your document photo, improve lighting and try again.",
    "error": "LOW_FACE_MATCH_SIMILARITY",
    "feedback_codes": ["LOW_FACE_MATCH_SIMILARITY"],
    "attempts_used": 1,
    "max_attempts": 3
  }
  
• Esgotamento - quando o limite se esgota, o status calculado é aplicado (Declined ou In Review).

​

Como funciona

---

​

Requisitos do documento

Para o melhor êxito na verificação, os documentos devem atender a estes padrões:

​

Requisitos gerais

• Emitido por um governo e válido dentro do período de validade configurado
• Fisicamente íntegro (sem danos, riscos ou manchas que escondam detalhes)
• Todas as informações críticas (nome completo, data de nascimento, MRZ etc.) claramente legíveis
• Dados consistentes em todos os documentos enviados

​

Requisitos da imagem

• Foto original e em tempo real (sem capturas de tela, digitalizações ou cópias digitais)
• Formatos compatíveis: JPG, JPEG, PNG, PDF
• Tamanho máximo do arquivo: 5MB
• Imagem colorida, com todos os cantos do documento visíveis
• Sem reflexos, sombras, edição digital ou manipulação
• Documentos físicos são obrigatórios (documentos digitais só são aceitos em regiões selecionadas onde são oficialmente reconhecidos)

​

Configurações adicionais por país e tipo de documento

Configure regras detalhadas por país e tipo de documento diretamente no console. Esses controles permitem adaptar os critérios de aceitação e as preferências de transcrição às suas necessidades de conformidade.

• Modo de validade: escolha como tratar documentos com data de validade vencida.
  • Rejeitar documentos expirados: se a data de validade do documento for anterior a hoje, marque-o como expirado e rejeite.
  • Permitir documentos expirados: não sinalize nem bloqueie documentos com data de validade vencida.
• Formato de caracteres preferido: selecione como os nomes e campos extraídos devem ser normalizados.
  • Prefira caracteres latinos (A–Z): exemplo: “Mohammed”
  • Prefira script original (não latino): exemplo: “محمد”
• Suporte regional e subtipos: ative documentos por região e especifique os subtipos aceitáveis quando um tipo de documento tiver muitas variações.
  • Exemplo: para carteiras de motorista dos Estados Unidos, selecione os subtipos exatos que você aceita (por exemplo, Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License etc.).
  • Use o controle “Subtipos aceitos” para incluir/excluir rapidamente muitas variantes (por exemplo, “128 selecionados”).

Dica: essas configurações se aplicam por país e tipo de documento, então você pode ser rigoroso em alguns mercados e mais flexível em outros.