Skip to main content

​
Resumo

As APIs ID Verification, Face Match e Liveness (KYC por sessão) retornam um campo warnings quando o provedor de verificação sinaliza problemas não bloqueantes ou flags de risco. warnings é um array de strings com códigos de risco (ex.: "POSSIBLE_DUPLICATED_USER", "LOW_FACE_MATCH_SIMILARITY"). Os clientes podem usar esses códigos para:
  • Exibição: Mapear cada código para uma mensagem legível (ex.: via i18n próprio ou as descrições abaixo).
  • Lógica: Agir conforme o código (ex.: UX diferente para DOCUMENT_EXPIRED vs POSSIBLE_DUPLICATED_USER).
Os códigos são por serviço: ID Verification, Face Match e Liveness têm cada um seu próprio conjunto. Abaixo estão os valores possíveis de cada um.
Se o provedor retornar um código não listado aqui, você ainda pode recebê-lo em warnings. Trate códigos desconhecidos como avisos genéricos e exiba o código ou uma mensagem de fallback.

​
ID Verification

Retornado em POST /api/kyc/id-verification e GET /api/kyc/id-verification/verifications/:id no array warnings.
CódigoDescrição
ID_DOCUMENT_IN_BLOCKLISTO documento corresponde a uma entrada da sua lista de documentos bloqueados (fraudulentos, roubados ou problemáticos).
BARCODE_NOT_DETECTEDNão foi possível localizar ou ler o código de barras do documento.
BARCODE_VALIDATION_FAILEDO código de barras não pôde ser validado com os demais dados do documento.
QR_NOT_DETECTEDNão foi possível localizar ou ler o código QR do documento.
QR_VALIDATION_FAILEDO código QR não pôde ser validado com os demais dados do documento.
MRZ_NOT_DETECTEDNão foi encontrada ou lida a zona de leitura mecânica (MRZ) do documento.
MINIMUM_AGE_NOT_META idade do usuário está abaixo do mínimo exigido.
DATA_INCONSISTENTOs dados OCR e do chip NFC não coincidem; possível alteração ou inconsistência.
COULD_NOT_RECOGNIZE_DOCUMENTNão foi possível confirmar a autenticidade ou validade do documento.
PORTRAIT_IMAGE_NOT_DETECTEDNão foi possível identificar ou processar a foto do documento.
DOCUMENT_NUMBER_NOT_DETECTEDNão foi possível localizar ou ler o número do documento.
DATE_OF_BIRTH_NOT_DETECTEDNão foi possível identificar a data de nascimento no documento.
EXPIRATION_DATE_NOT_DETECTEDNão foi possível identificar a data de validade no documento.
NAME_NOT_DETECTEDNão foi possível identificar o nome e/ou sobrenome no documento.
MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAMEHá diferenças entre o MRZ e os dados extraídos por OCR; possível alteração do documento.
MRZ_VALIDATION_FAILEDO MRZ não atende ao formato esperado ou contém dados inválidos.
INVALID_DATEUma ou mais datas do documento não são válidas ou não coincidem com o formato esperado.
DOCUMENT_EXPIREDA data de validade do documento já passou.
DOCUMENT_NOT_SUPPORTED_FOR_APPLICATIONO tipo de documento não é aceito neste processo de verificação.
DOCUMENT_SIDES_MISMATCHAs faces do documento não coincidem com o formato esperado.
COULD_NOT_DETECT_DOCUMENT_TYPENão foi possível determinar o tipo de documento enviado.
DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTSO nome neste documento não coincide com o de outros documentos já verificados para este usuário.
POSSIBLE_DUPLICATED_USERO sistema identificou um possível usuário duplicado com documentos aprovados em outra sessão; investigação necessária.
LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITYO rosto capturado não corresponde suficientemente à foto do documento.
FULL_NAME_MISMATCH_WITH_PROVIDEDO nome completo fornecido não coincide com o extraído do documento.
DOB_MISMATCH_WITH_PROVIDEDA data de nascimento fornecida não coincide com a do documento.
GENDER_MISMATCH_WITH_PROVIDEDO gênero fornecido não coincide com o do documento.
COUNTRY_MISMATCH_WITH_PROVIDEDO país fornecido não coincide com o do documento.
NATIONALITY_MISMATCH_WITH_PROVIDEDA nacionalidade fornecida não coincide com a do documento.
IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDEDO número de identificação fornecido não coincide com o do documento.
SCREEN_CAPTURE_DETECTEDO documento parece ser captura de tela ou foto de documento exibido na tela, não o físico.
PRINTED_COPY_DETECTEDO documento parece ser uma cópia impressa, não o original oficial.
PORTRAIT_MANIPULATION_DETECTEDFoi detectada possível manipulação da área da foto do documento.
UNPARSED_ADDRESSO endereço do documento não pôde ser interpretado ou geolocalizado.
DOCUMENT_NUMBER_FORMAT_MISMATCHO número do documento não coincide com o formato esperado para este tipo.
PERSONAL_NUMBER_FORMAT_MISMATCHO número pessoal não coincide com o formato esperado para este tipo de documento.
ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTSOs dados extraídos de vários documentos desta sessão não coincidem (nome ou data de nascimento).

​
Face Match

Retornado em POST /api/kyc/face-match e GET /api/kyc/face-match/verifications/:id no array warnings.
CódigoDescrição
LOW_FACE_MATCH_SIMILARITYOs traços faciais da imagem não correspondem suficientemente à imagem de referência.
NO_REFERENCE_IMAGEFalta uma imagem de referência para a comparação facial.

​
Liveness (KYC por sessão)

Retornado nas respostas de validação KYC por sessão (ex.: validação atual, listagem) quando são realizadas verificações de vivacidade. O array warnings do payload pode conter estes códigos.
CódigoDescrição
FACE_IN_BLOCKLISTO rosto corresponde a uma entrada da sua lista de rostos bloqueados.
POSSIBLE_FACE_IN_BLOCKLISTO sistema identificou um possível rosto na lista de bloqueados.
LOW_LIVENESS_SCOREA verificação de vivacidade resultou em pontuação baixa.
NO_FACE_DETECTEDNão foi identificado um rosto durante a verificação de vivacidade.
LIVENESS_FACE_ATTACKFoi detectada possível tentativa de burlar a verificação de vivacidade.
DUPLICATED_FACEFoi identificado um rosto duplicado de outra sessão aprovada.
POSSIBLE_DUPLICATED_FACEEste rosto pode coincidir com outro usuário já aprovado no sistema.
MULTIPLE_FACES_DETECTEDForam detectados vários rostos na imagem. É usado o maior para a verificação. (Apenas Liveness passivo)
LOW_FACE_QUALITYA qualidade da imagem facial está abaixo do limite aceitável. (Apenas Liveness passivo)
LOW_FACE_LUMINANCEA imagem facial está muito escura. (Apenas Liveness passivo)
HIGH_FACE_LUMINANCEA imagem facial está muito clara ou superexposta. (Apenas Liveness passivo)

​
Exemplo de resposta (ID Verification)

{
  "status": "approved",
  "verificationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "requestId": "req_abc",
  "extractedData": { "fullName": "Jane Doe", "documentNumber": "12345678" },
  "warnings": ["POSSIBLE_DUPLICATED_USER"]
}

​
Exemplo de resposta (Face Match)

{
  "match": true,
  "score": 85,
  "status": "approved",
  "verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "warnings": []
}

ID Verification

Verificar frente/verso do documento e extrair dados

Face Match

Comparar foto do documento e selfie