Códigos de risco em avisos KYC

Resumo

As APIs ID Verification, Face Match e Liveness retornam um campo warnings quando o serviço de verificação sinaliza problemas não bloqueantes ou flags de risco. O KYC por sessão (POST /api/kyc/validations, GET /api/kyc/validations/:id) persiste um array warnings na validação fundindo códigos de documento, liveness, face match e AML, e pode acrescentar códigos internos Gu1 (ex.: listas ou sandbox). Os clientes podem usá-los para:

Exibição: Mapear cada código para uma mensagem (i18n próprio ou as descrições abaixo; no dashboard gu1 as etiquetas seguem a ordem de chaves em warningRisks e rejectionReasonCodes nos arquivos de idioma do produto).
Lógica: Agir por código ou enviar códigos permitidos em omitWarnings ao criar uma validação.

Nas APIs pontuais os códigos são por serviço; na validação por sessão usa-se a união dos serviços mais códigos internos. Abaixo estão os valores documentados.

Se o serviço 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.

KYC por sessão

Em GET /api/kyc/validations/:id (e listagens), o array warnings da validação contém strings de código de risco obtidas de:

Etapa de verificação de documento
Etapa de liveness
Etapa de face match
Objetos de AML na decisão da sessão
Análise de dispositivo e IP na decisão da sessão (ip_analyses[] / ip_analysis)

Códigos adicionais podem ser acrescentados por regras Gu1 (ex.: listas de bloqueio da organização). O campo opcional omitWarnings em POST /api/kyc/validations usa as mesmas strings documentadas nas tabelas abaixo.

ID Verification

Retornado em POST /api/kyc/id-verification e GET /api/kyc/id-verification/verifications/:id no array warnings. Os mesmos códigos podem aparecer em validações por sessão na etapa de documento.

Código	Descrição
`ID_DOCUMENT_IN_BLOCKLIST`	O documento corresponde a uma entrada da sua lista de documentos bloqueados (fraudulentos, roubados ou problemáticos).
`BARCODE_NOT_DETECTED`	Não foi possível localizar ou ler o código de barras do documento.
`BARCODE_VALIDATION_FAILED`	O código de barras não pôde ser validado com os demais dados do documento.
`QR_NOT_DETECTED`	Não foi possível localizar ou ler o código QR do documento.
`QR_VALIDATION_FAILED`	O código QR não pôde ser validado com os demais dados do documento.
`MRZ_NOT_DETECTED`	Não foi encontrada ou lida a zona de leitura mecânica (MRZ) do documento.
`MINIMUM_AGE_NOT_MET`	A idade do usuário está abaixo do mínimo exigido.
`DATA_INCONSISTENT`	Os dados OCR e do chip NFC não coincidem; possível alteração ou inconsistência.
`COULD_NOT_RECOGNIZE_DOCUMENT`	Não foi possível confirmar a autenticidade ou validade do documento.
`PORTRAIT_IMAGE_NOT_DETECTED`	Não foi possível identificar ou processar a foto do documento.
`IMAGE_TOO_BLURRY`	A imagem do documento está muito desfocada; capture novamente com melhor foco.
`IMAGE_TOO_DARK`	A imagem do documento está muito escura; melhore a iluminação ao capturar.
`IMAGE_TOO_BRIGHT`	A imagem do documento está muito clara ou superexposta; evite luz direta ao capturar.
`DOCUMENT_NUMBER_NOT_DETECTED`	Não foi possível localizar ou ler o número do documento.
`DATE_OF_BIRTH_NOT_DETECTED`	Não foi possível identificar a data de nascimento no documento.
`EXPIRATION_DATE_NOT_DETECTED`	Não foi possível identificar a data de validade no documento.
`NAME_NOT_DETECTED`	Não foi possível identificar o nome e/ou sobrenome no documento.
`MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`	Há diferenças entre o MRZ e os dados extraídos por OCR; possível alteração do documento.
`MRZ_VALIDATION_FAILED`	O MRZ não atende ao formato esperado ou contém dados inválidos.
`INVALID_DATE`	Uma ou mais datas do documento não são válidas ou não coincidem com o formato esperado.
`DOCUMENT_EXPIRED`	A data de validade do documento já passou.
`DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`	O tipo de documento não é aceito neste processo de verificação.
`DOCUMENT_SIDES_MISMATCH`	As faces do documento não coincidem com o formato esperado.
`COULD_NOT_DETECT_DOCUMENT_TYPE`	Não foi possível determinar o tipo de documento enviado.
`DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`	O nome neste documento não coincide com o de outros documentos já verificados para este usuário.
`POSSIBLE_DUPLICATED_USER`	O sistema identificou um possível usuário duplicado com documentos aprovados em outra sessão; investigação necessária.
`LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY`	O rosto capturado não corresponde suficientemente à foto do documento.
`FULL_NAME_MISMATCH_WITH_PROVIDED`	O nome completo fornecido não coincide com o extraído do documento.
`DOB_MISMATCH_WITH_PROVIDED`	A data de nascimento fornecida não coincide com a do documento.
`GENDER_MISMATCH_WITH_PROVIDED`	O gênero fornecido não coincide com o do documento.
`COUNTRY_MISMATCH_WITH_PROVIDED`	O país fornecido não coincide com o do documento.
`NATIONALITY_MISMATCH_WITH_PROVIDED`	A nacionalidade fornecida não coincide com a do documento.
`IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED`	O número de identificação fornecido não coincide com o do documento.
`SCREEN_CAPTURE_DETECTED`	O documento parece ser captura de tela ou foto de documento exibido na tela, não o físico.
`PRINTED_COPY_DETECTED`	O documento parece ser uma cópia impressa, não o original oficial.
`PORTRAIT_MANIPULATION_DETECTED`	Foi detectada possível manipulação da área da foto do documento.
`UNPARSED_ADDRESS`	O endereço do documento não pôde ser interpretado ou geolocalizado.
`DOCUMENT_NUMBER_FORMAT_MISMATCH`	O número do documento não coincide com o formato esperado para este tipo.
`PERSONAL_NUMBER_FORMAT_MISMATCH`	O número pessoal não coincide com o formato esperado para este tipo de documento.
`ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS`	Os dados extraídos de vários documentos desta sessão não coincidem (nome ou data de nascimento).
`GUENO_KYC_ORG_BLOCKLIST_HIT`	Fluxo de rejeição automática: um valor desta validação correspondeu a uma lista de bloqueio KYC da organização (sinal agregado).
`GUENO_KYC_ORG_BLOCKLIST_IP`	Lista de bloqueio KYC da organização: o IP da sessão correspondeu a uma lista de enforcement.
`GUENO_KYC_ORG_BLOCKLIST_DOCUMENT`	Lista de bloqueio KYC da organização: o número do documento correspondeu a uma lista de enforcement.
`GUENO_KYC_ORG_BLOCKLIST_PERSONAL`	Lista de bloqueio KYC da organização: o número pessoal / trâmite correspondeu a uma lista de enforcement.
`GUENO_KYC_ORG_MINIMUM_AGE_NOT_MET`	Política de idade mínima da organização (configurações KYC): a data de nascimento extraída implica menos anos completos do que o limiar configurado; a validação fica rejeitada mesmo que o OCR tenha validado a identidade. Se não houver data de nascimento interpretável, não se aplica.

Face Match

Retornado em POST /api/kyc/face-match e GET /api/kyc/face-match/verifications/:id no array warnings.

Código	Descrição
`LOW_FACE_MATCH_SIMILARITY`	Os traços faciais da imagem não correspondem suficientemente à imagem de referência.
`NO_REFERENCE_IMAGE`	Falta 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ódigo	Descrição
`FACE_IN_BLOCKLIST`	O rosto corresponde a uma entrada da sua lista de rostos bloqueados.
`POSSIBLE_FACE_IN_BLOCKLIST`	O sistema identificou um possível rosto na lista de bloqueados.
`LOW_LIVENESS_SCORE`	A verificação de vivacidade resultou em pontuação baixa.
`NO_FACE_DETECTED`	Não foi identificado um rosto durante a verificação de vivacidade.
`LIVENESS_FACE_ATTACK`	Foi detectada possível tentativa de burlar a verificação de vivacidade.
`DUPLICATED_FACE`	Foi identificado um rosto duplicado de outra sessão aprovada.
`POSSIBLE_DUPLICATED_FACE`	Este rosto pode coincidir com outro usuário já aprovado no sistema.
`MULTIPLE_FACES_DETECTED`	Foram detectados vários rostos na imagem. É usado o maior para a verificação. (Apenas Liveness passivo)
`LOW_FACE_QUALITY`	A qualidade da imagem facial está abaixo do limite aceitável. (Apenas Liveness passivo)
`LOW_FACE_LUMINANCE`	A imagem facial está muito escura. (Apenas Liveness passivo)
`HIGH_FACE_LUMINANCE`	A imagem facial está muito clara ou superexposta. (Apenas Liveness passivo)

AML (KYC por sessão)

Quando o AML roda dentro da sessão, os códigos de risco das warnings do screening são fundidos no array warnings da validação.

Código	Descrição
`POSSIBLE_MATCH_FOUND`	O screening AML encontrou possíveis coincidências com listas ou bases de alto risco; pode exigir revisão.
`COULD_NOT_PERFORM_AML_SCREENING`	O screening AML não pôde ser concluído com os dados disponíveis (ex.: faltam campos obrigatórios).

Análise de dispositivo e IP (KYC por sessão)

Quando a análise de dispositivo e IP roda dentro da sessão, os códigos de risco de ip_analyses[].warnings[] (ou legacy ip_analysis.warnings) são fundidos no array warnings da validação.

Código	Descrição
`PRIVATE_NETWORK_DETECTED`	A sessão foi aberta via VPN, proxy ou nó de saída Tor.
`COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP`	O país do documento de identidade difere do país derivado do endereço IP.
`EXPECTED_IP_ADDRESS_MISMATCH`	O IP ao vivo difere do IP esperado informado na criação da sessão.
`IP_ADDRESS_IN_BLOCKLIST`	O endereço IP da sessão coincide com uma entrada na blocklist de IP do provedor (força recusa no provedor).
`DEVICE_FINGERPRINT_IN_BLOCKLIST`	A impressão digital do dispositivo coincide com uma entrada na blocklist de dispositivos do provedor (força recusa no provedor).
`DUPLICATED_IP_ADDRESS`	O mesmo endereço IP foi usado em outra sessão com um identificador de usuário diferente (`vendor_data`).
`DUPLICATED_DEVICE_FINGERPRINT`	A mesma impressão digital persistente do dispositivo foi reutilizada em sessões com identificadores de usuário diferentes.
`DEVICE_RECOVERED_HIGH_CONFIDENCE`	Recuperação de dispositivo com alta confiança: a sessão corresponde a um dispositivo visto anteriormente após mudança do ID persistente (ex.: anônimo, limpeza de armazenamento ou reinstalação).

Internos (Gu1)

Códigos que o Gu1 pode acrescentar (entidade vs OCR, política de nome, sandbox, etc.) e aparecer em warnings da validação por sessão quando aplicável.

Código	Descrição
`GUENO_DOCUMENT_NUMBER_MISMATCH`	O número do documento da verificação não coincide com o da entidade no momento do chequeio.
`GUENO_PERSONAL_NUMBER_MISMATCH`	Os chequeios de documento/pessoal contra a entidade não se alinham como exigido.
`GUENO_KYC_NAME_SIMILARITY_BELOW_MIN`	A similaridade do nome da entidade com o derivado do documento está abaixo do mínimo da organização.
`GUENO_CROSS_ENTITY_DUPLICATED`	Gu1 confirmou que as referências de rosto/sessão duplicada pertencem a outra entidade da mesma organização (`metadata.kycCrossEntityDuplicates.matches`). Se o OCR mapeou `approved`, Gu1 define o status como `in_review` para revisão manual. Não omitível: não pode constar em `omitWarnings` nem ser auto-aprovado por omit. Matches contra outra entidade com o mesmo tax ID (normalizado) da entidade avaliada não contam como cross-entity.
`SANDBOX_KYC_REJECTED_DEFAULT`	Resultado de teste em sandbox: validação rejeitada quando o tax ID coincidiu com a lista de teste.

Duplicados cross-entity: Códigos do provedor como DUPLICATED_FACE ou POSSIBLE_DUPLICATED_USER só permanecem quando Gu1 resolve match em outra entidade; caso contrário podem ser suprimidos (metadata.kycCrossEntityDuplicates.suppressedWarnings). GUENO_CROSS_ENTITY_DUPLICATED nunca é omitível.

Cruzamento com registro (Argentina / RENAPER)

Com dupla verificação RENAPER ativada, se um problema de registro for exposto como código em warnings, podem ser usadas as mesmas strings. Nos idiomas do produto costumam mapear em rejectionReasonCodes (e fallbacks onde aplicável).

Código	Descrição
`RENAPER_DNI_MISSING`	Não foi possível executar o cruzamento: não há número de documento (DNI) a partir da verificação.
`RENAPER_GENDER_MISSING`	Não foi possível executar o cruzamento: é necessário gênero (M/F) para o registro.
`RENAPER_VERIFICATION_UNAVAILABLE`	O registro não pôde ser concluído; tente mais tarde.
`RENAPER_DNI_NOT_MATCH`	O número do documento não coincide com o registro oficial.
`RENAPER_TRAMITE_DATA_MISSING`	Não foi possível comparar o número de trâmite: faltam dados obrigatórios.
`RENAPER_TRAMITE_ID_NOT_MATCH`	O número de trâmite não coincide com o registro (ex.: cópia de DNI desatualizada).
`RENAPER_NAME_NOT_MATCH`	O nome do OCR está abaixo do limiar de 80% de similaridade com o registro RENAPER.
`RENAPER_EJEMPLAR_NOT_MATCH`	O exemplar do documento não coincide com o registro RENAPER.
`RENAPER_DOB_NOT_MATCH`	A data de nascimento do OCR não coincide com `fecha_nacimiento` do RENAPER.
`RENAPER_EXPIRY_NOT_MATCH`	A data de vencimento do OCR não coincide com `vencimiento` do RENAPER.
`RENAPER_BIOMETRIC_NOT_MATCH`	A selfie não coincide com a foto do documento no registro biométrico.
`RENAPER_BIOMETRIC_UNAVAILABLE`	Não foi possível completar o chequeo biométrico (rede, credenciais ou serviço).
`RENAPER_CREDENTIALS_REQUIRED`	Faltam credenciais RENAPER configuradas para a organização.
`RENAPER_NOT_VALID_CREDENTIALS`	As credenciais RENAPER não são válidas.

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

Começando

SDK

Casos de Uso

Webhooks

Workflows

Monitoramento (entidades)

Pessoa

Mensagens

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Listas de dados

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Importações em lote

Enriquecimento

Serviços

Integrações

Tutoriais Interativos

Códigos de risco em avisos KYC

Resumo

KYC por sessão

ID Verification

Face Match

Liveness (KYC por sessão)

AML (KYC por sessão)

Análise de dispositivo e IP (KYC por sessão)

Internos (Gu1)

Cruzamento com registro (Argentina / RENAPER)

Exemplo de resposta (ID Verification)

Exemplo de resposta (Face Match)

ID Verification

Face Match

​Resumo

​KYC por sessão

​ID Verification

​Face Match

​Liveness (KYC por sessão)

​AML (KYC por sessão)

​Análise de dispositivo e IP (KYC por sessão)

​Internos (Gu1)

​Cruzamento com registro (Argentina / RENAPER)

​Exemplo de resposta (ID Verification)

​Exemplo de resposta (Face Match)

ID Verification

Face Match

Resumo

KYC por sessão

ID Verification

Face Match

Liveness (KYC por sessão)

AML (KYC por sessão)

Análise de dispositivo e IP (KYC por sessão)

Internos (Gu1)

Cruzamento com registro (Argentina / RENAPER)

Exemplo de resposta (ID Verification)

Exemplo de resposta (Face Match)