> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Códigos de risco em avisos KYC
> Referência de strings de código de risco em warnings para KYC por sessão, ID Verification, Face Match e Liveness na API KYC da gu1.
## 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](/pt/use-cases/kyc/create-validation).
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`](/pt/use-cases/kyc/create-validation) 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)
```json theme={null}
{
"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)
```json theme={null}
{
"match": true,
"score": 85,
"status": "approved",
"verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"warnings": []
}
```
Verificar frente/verso do documento e extrair dados
Comparar foto do documento e selfie