> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Avisos e códigos de erro da verificação NFC > Consulte os avisos do módulo NFC da Didit, incluindo leitura de chip ignorada, discrepâncias de OCR e certificados expirados, causas e correções. ## Visão geral Os avisos no relatório de NFC assinalam todas as condições que a Didit observou durante a leitura e validação do chip. Ficam registados no array `warnings[]` em cada item de `nfc_verifications[]` (consulte o [relatório de NFC](https://docs.didit.me/pt/core-technology/nfc-verification/report-nfc-verification.md)), com `feature` definido como `"NFC"`. Cada entrada segue o formato partilhado do [objeto de aviso](https://docs.didit.me/pt/reference/data-models.md#objeto-de-aviso): `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`. Cada aviso tem três camadas: 1. **O código `risk`** — um identificador estável que pode usar para fazer correspondência no seu código (os códigos listados abaixo). 2. **O `log_type`** — um de `information`, `warning` ou `error`. É derivado da ação que o seu fluxo configura para esse risco: **Sem ação** → `information`, **Revisão** → `warning`, **Recusar** → `error`. 3. **O impacto na decisão** — a mesma ação configurada também determina o `status` do relatório de NFC: uma ação de Revisão altera-o para `In Review`, e uma ação de recusa para `Declined`. Quatro riscos de NFC são configuráveis desta forma (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME`), além dos cinco riscos do [Japan My Number Card](#japan-my-number-card-jpki), cada um com a sua própria configuração. Os dois riscos de certificado (`DSC_CERTIFICATE_REVOKED`, `DSC_CERTIFICATE_EXPIRED`) são **apenas informativos**: incluem sempre `log_type: "information"` e nunca alteram o estado de NFC por si próprios. O conjunto completo de códigos de risco gerados pelo módulo de NFC encontra-se abaixo. Não existem outros códigos de risco de NFC. ## Avisos gerados | `risk` | Causa | Gravidade (`log_type`) | Afeta o estado? | Correção | | - | - | - | - | - | | `SKIPPED_NFC_VALIDATION` | A leitura do chip foi ignorada — o fluxo permite ignorar (`allow_nfc_skip`) e o utilizador tocou em ignorar, ou o cliente ignorou porque não conseguiu ler NFC. O motivo exato é registado em `additional_data.skip_reason` (consulte [Motivos para ignorar](#motivos-para-ignorar)) e determina a `long_description` do aviso. | Segue a definição de **ação ao ignorar NFC** (`skip_nfc_action`): informação / aviso / erro. | Configurável — Sem ação, Revisão ou Recusar. | Se a sua política exigir NFC, defina a ação ao ignorar para Recusar (ou proíba totalmente ignorar) e instrua o utilizador a tentar novamente a partir de um dispositivo com capacidade NFC. Caso contrário, mantenha Sem ação para recorrer apenas à verificação por OCR. | | `NFC_CHIP_NOT_VERIFIED` | O chip foi lido, mas falhou a verificação criptográfica por um motivo diferente de uma âncora de confiança em falta explicitamente identificada. Um hash de Data Group, a assinatura SOD ou outra verificação de autenticação passiva falhou. | Segue a definição de **ação de chip não verificado** (`unverified_chip_action`). | Configurável — Sem ação, Revisão ou Recusar. | Trate isto como um chip potencialmente inválido ou adulterado. Inspecione `authenticity` e `certificate_summary.validation` para ver qual verificação falhou. | | `NFC_TRUST_ANCHOR_MISSING` | O Document Signer Certificate (DSC) do chip pertence a uma geração de Country Signing Certification Authority (CSCA) que não está disponível no repositório de confiança da Didit (`certificate_summary.validation.csca_missing` é `true`). A Didit não consegue, por isso, estabelecer a cadeia de confiança do SOD. | Segue a definição de **ação de chip não verificado** (`unverified_chip_action`). | Configurável — Sem ação, Revisão ou Recusar. | Trata-se de uma falha de cobertura do repositório de confiança, e não de evidência de que o chip foi adulterado. Reveja o documento através das suas verificações alternativas e contacte o suporte da Didit com o país emissor para que a CSCA em falta possa ser investigada. | | `NFC_AND_OCR_DATA_NOT_SAME` | A MRZ lida do chip não corresponde à MRZ obtida por OCR do lado visível do documento (após a normalização de ambas, ignorando o preenchimento `<`). Forte indício de adulteração. | Segue a definição de **ação de inconsistência de dados** (`inconsistent_data_action`) — a mesma definição que rege as verificações de consistência de dados da verificação de identidade. | Configurável — Sem ação, Revisão ou Recusar. | Trate como adulteração a menos que provado em contrário; Recusar é a definição habitual. O payload `additional_data` inclui as linhas da MRZ de OCR (`ocr_mrz`, array) e a MRZ do chip (`nfc_mrz`, string única) para comparação manual. | | `DSC_CERTIFICATE_REVOKED` | O Document Signer Certificate que assinou este chip surge na Certificate Revocation List (CRL) do país emissor. | Sempre `information`. | Não — nunca altera o estado do NFC por si só. | Forte indício de que a chave de assinatura pode ter sido comprometida; encaminhe estas sessões para revisão manual através da sua própria lógica, se necessário. Note que o aviso `NFC_CHIP_NOT_VERIFIED` também é normalmente gerado, sendo configurável. | | `DSC_CERTIFICATE_EXPIRED` | A janela de validade do DSC expirou (`certificate_summary.validation.dsc_expired` é `true`). | Sempre `information`. | Não — nunca altera o estado do NFC por si só. | Comum em documentos mais antigos. Tal como na revogação, um DSC expirado também falha a validação completa do SOD, pelo que o aviso `NFC_CHIP_NOT_VERIFIED` também é gerado e segue a ação configurada. | | `JPKI_CERTIFICATE_INVALID` | Japan My Number Card: um certificado lido do cartão não forma uma cadeia de confiança com a autoridade de certificação JPKI do seu tipo, está fora do seu período de validade ou não é um certificado My Number Card desse tipo. `additional_data.certificate_types` lista os certificados que falharam; `jpki.certificates[].failure` indica o motivo. | Segue `jpki_certificate_invalid_action` (predefinição Recusar). | Configurável: Sem ação, Revisão ou Recusar. | Trate como um cartão inválido ou adulterado. Um certificado de cartão expirado também se enquadra aqui: o titular renova-o no seu município. | | `JPKI_SIGNATURE_INVALID` | Japan My Number Card: a assinatura do cartão sobre o desafio de utilização única não pode ser verificada com o seu certificado, pelo que a posse do cartão e o conhecimento do seu PIN não são comprovados. Também emitido quando o passo de NFC foi encerrado sem qualquer leitura de cartão (`additional_data.certificate_types` fica então vazio). | Segue `jpki_signature_invalid_action` (predefinição Recusar). | Configurável: Sem ação, Revisão ou Recusar. | Não aceite a leitura do cartão como prova. Peça à pessoa para tentar novamente com o cartão físico. | | `JPKI_CERTIFICATE_REVOKED` | Japan My Number Card: a verificação de revogação indica que um certificado foi revogado, por exemplo, porque o cartão foi dado como perdido ou o registo do titular foi alterado (`jpki.revocation_status` é `revoked`). | Segue `jpki_certificate_revoked_action` (predefinição Recusar). | Configurável: Sem ação, Revisão ou Recusar. | Não aceite o cartão. | | `JPKI_REVOCATION_UNCHECKED` | Japan My Number Card: os certificados e a assinatura foram verificados, mas não estava disponível nenhuma resposta de revogação (`jpki.revocation_status` é `unchecked`), pelo que não é possível excluir a possibilidade de o cartão estar revogado. Não é emitido quando a cadeia ou a assinatura já tiverem falhado. | Segue `jpki_revocation_unchecked_action` (predefinição Revisão). | Configurável: Sem ação, Revisão ou Recusar. | Decida qual o valor que um cartão verificado sem resposta de revogação tem para si e defina a ação em conformidade. | | `JPKI_AND_OCR_DATA_NOT_SAME` | Japan My Number Card: o nome, a data de nascimento, o sexo ou a morada no certificado de assinatura diferem dos dados lidos a partir da fotografia do mesmo cartão. `additional_data.fields` indica os atributos que diferem, nunca os seus valores. | Segue `jpki_inconsistent_data_action` (predefinição Revisão). | Configurável: Sem ação, Revisão ou Recusar. | Compare `jpki.attributes` com os dados de verificação de identidade antes de decidir. Um nome com um caráter invulgar pode diferir porque o certificado contém um caráter substituto (`jpki.attributes.name_substitute_characters`). | > [!NOTE] > > `SKIPPED_NFC_VALIDATION` é mutuamente exclusivo com `NFC_CHIP_NOT_VERIFIED` e `NFC_TRUST_ANCHOR_MISSING`: os avisos de verificação do chip só são avaliados quando a leitura do chip não foi ignorada. Os dois avisos de verificação do chip também são mutuamente exclusivos. ## Strings de descrição exatas A API devolve exatamente estas strings de `short_description` e `long_description` para cada risco: | `risk` | `short_description` | `long_description` | | - | - | - | | `SKIPPED_NFC_VALIDATION` | Validação NFC ignorada | Específica do motivo — consulte [Motivos para ignorar](#motivos-para-ignorar). Recorre por defeito a "The Near Field Communication (NFC) chip validation process was not completed, potentially due to technical issues or lack of NFC support." em sessões antigas registadas antes da existência de motivos para ignorar. | | `NFC_CHIP_NOT_VERIFIED` | Chip NFC não verificado | O chip Near Field Communication (NFC) falhou a autenticação passiva por um motivo diferente de uma âncora de confiança em falta explicitamente identificada. Os dados ou a assinatura do chip podem ser inválidos ou ter sido alterados. | | `NFC_TRUST_ANCHOR_MISSING` | Âncora de confiança NFC indisponível | Não foi possível verificar o chip Near Field Communication (NFC) porque a âncora de confiança da Country Signing Certification Authority (CSCA) do país emissor não está disponível. Trata-se de uma falha de cobertura do repositório de confiança, e não de uma evidência de que o chip tenha sido alterado. | | `NFC_AND_OCR_DATA_NOT_SAME` | Dados do NFC e do OCR não são iguais | Os dados do chip Near Field Communication (NFC) e os dados de OCR não coincidem, o que indica uma potencial adulteração do documento ou inconsistência de dados. | | `DSC_CERTIFICATE_REVOKED` | Document Signer Certificate revogado | O Document Signer Certificate (DSC) utilizado para assinar os dados do chip do passaporte eletrónico foi revogado pela Certificate Revocation List (CRL) do país emissor, indicando que a chave de assinatura pode ter sido comprometida. | | `DSC_CERTIFICATE_EXPIRED` | Document Signer Certificate expirado | O Document Signer Certificate (DSC) utilizado para assinar os dados do chip do passaporte eletrónico expirou, o que significa que o período de validade do certificado terminou. | | `JPKI_CERTIFICATE_INVALID` | Certificado do My Number Card inválido | Um certificado lido do chip do My Number Card não é válido: não estabelece cadeia até à autoridade de certificação da infraestrutura de chaves públicas japonesa (JPKI), está fora do seu período de validade ou não é um certificado do My Number Card do tipo solicitado. | | `JPKI_SIGNATURE_INVALID` | Assinatura do My Number Card inválida | A assinatura feita pelo My Number Card sobre o desafio de verificação de utilização única não é validada com o certificado do cartão, pelo que a posse do cartão e o conhecimento do respetivo PIN não são comprovados. | | `JPKI_CERTIFICATE_REVOKED` | Certificado do My Number Card revogado | A verificação de revogação indica que um certificado lido do My Number Card foi revogado, por exemplo, porque o cartão foi comunicado como perdido ou o registo do titular foi alterado. | | `JPKI_REVOCATION_UNCHECKED` | Estado de revogação do My Number Card não verificado | O certificado e a assinatura do My Number Card foram verificados, mas não foi possível verificar o seu estado de revogação, pelo que a possibilidade de um cartão revogado não pode ser descartada. | | `JPKI_AND_OCR_DATA_NOT_SAME` | Dados do chip do My Number Card e do OCR não são iguais | O nome, a data de nascimento, o sexo ou a morada no certificado de assinatura do My Number Card não coincidem com os dados lidos da imagem do cartão (OCR), o que indica uma possível substituição ou inconsistência de dados. | ## Motivos para ignorar Os avisos `SKIPPED_NFC_VALIDATION` incluem `additional_data.skip_reason`, um dos sete códigos estáveis que indicam exatamente o motivo pelo qual o NFC não foi executado (em sessões registadas antes de existirem os motivos para ignorar, `additional_data` pode ser `null` — trate o campo como opcional ao processar decisões históricas). A mesma taxonomia surge ao nível da sessão como `nfc_skip_reason` no payload da decisão — inclusive nas sessões em que o NFC nunca poderia ter sido executado (documento sem chip, integração web) e, portanto, nenhum relatório ou aviso de NFC existe. | `skip_reason` | Significado | `long_description` | | - | - | - | | `USER_SKIPPED` | O NFC foi disponibilizado num dispositivo compatível e o utilizador optou por ignorar. | A etapa de leitura do chip NFC foi disponibilizada num dispositivo compatível, mas o utilizador optou por ignorá-la (ignorar é permitido pela configuração do fluxo). | | `DOCUMENT_WITHOUT_CHIP` | O modelo do documento não tem um chip NFC legível (não é um documento eletrónico ICAO 9303). | Não foi possível realizar a verificação NFC porque este documento não tem um chip NFC legível: não é um documento eletrónico ICAO 9303. | | `CHIP_CERTIFICATE_UNAVAILABLE` | O chip existe, mas nenhum certificado de assinatura do país emissor (CSCA) abrange o período de emissão do documento, pelo que a assinatura não pode ser verificada. | Não foi possível realizar a verificação NFC porque o certificado de assinatura do país emissor (CSCA) que abrange o período de emissão deste documento não está disponível, pelo que a assinatura do chip não pode ser verificada. | | `DEVICE_WITHOUT_NFC` | Um SDK nativo comunicou que o telemóvel não tem leitor NFC disponível. | Não foi possível realizar a verificação NFC porque o dispositivo do utilizador comunicou que não tem um leitor NFC disponível. | | `INTEGRATION_WITHOUT_NFC_ACCESS` | A verificação foi executada sem um SDK nativo (por exemplo, num navegador web), o qual não tem acesso ao leitor NFC do telemóvel. | Não foi possível realizar a verificação NFC porque a verificação não foi executada através de um SDK móvel nativo, pelo que não houve acesso ao leitor NFC do telemóvel (os navegadores web não conseguem ler chips NFC). | | `MRZ_KEY_UNAVAILABLE` | A chave de acesso ao chip (semente BAC/PACE) não pôde ser derivada a partir da MRZ do documento. | Não foi possível realizar a verificação NFC porque a chave de acesso ao chip não pôde ser derivada a partir da zona de leitura ótica (MRZ) do documento. | | `JPKI_UNAVAILABLE` | O documento é um Japan My Number Card, cujo chip é lido através de JPKI, e o JPKI não estava disponível para esta verificação: não está ativado, ou a versão do SDK nativo da aplicação não consegue ler My Number Cards. Um My Number Card verificado num navegador recebe `INTEGRATION_WITHOUT_NFC_ACCESS`, e num telemóvel sem NFC recebe `DEVICE_WITHOUT_NFC`, tal como acontece com qualquer chip. | Não foi possível realizar a verificação NFC porque este My Number Card é lido através de JPKI, que não estava disponível para esta verificação: não está ativado, ou o SDK da aplicação não consegue ler My Number Cards. | > [!NOTE] > > Um relatório de NFC e o respetivo aviso `SKIPPED_NFC_VALIDATION` só existem quando o cliente chegou à etapa de NFC e a ignorou explicitamente (tipicamente `USER_SKIPPED`, ou `DEVICE_WITHOUT_NFC` quando o leitor se revelou indisponível no momento da leitura). Quando a etapa de NFC foi contornada antes de poder sequer ser disponibilizada — documento sem chip, certificado em falta, ausência de capacidade NFC comunicada, chave MRZ ilegível, JPKI indisponível — nenhum relatório ou aviso é criado e o motivo surge apenas no campo `nfc_skip_reason` ao nível da sessão, sem afetar o estado da sessão. ## Configuração Três definições de fluxo controlam a forma como os avisos de NFC são encaminhados. Cada uma pode ser definida como **Sem ação**, **Revisão** ou **Recusar**: 1. **Ação ao ignorar NFC** (`skip_nfc_action`) — aplica-se a `SKIPPED_NFC_VALIDATION`. A opção de ignorar só é disponibilizada aos utilizadores quando `allow_nfc_skip` está ativado. 2. **Ação para chip não verificado** (`unverified_chip_action`) — aplica-se tanto a `NFC_CHIP_NOT_VERIFIED` como a `NFC_TRUST_ANCHOR_MISSING`, para que o comportamento do estado da sessão permaneça o mesmo enquanto o código de risco explica o motivo da falha na verificação. 3. **Ação para inconsistência de dados** (`inconsistent_data_action`) — aplica-se a `NFC_AND_OCR_DATA_NOT_SAME`. Esta é a mesma definição de inconsistência de dados utilizada pela verificação de identidade. Os dois riscos `DSC_CERTIFICATE_*` não têm definição de ação — são sempre informativos. Os riscos do Japan My Number Card têm mais cinco definições, listadas na secção seguinte. ## Japan My Number Card (JPKI) Um Japan My Number Card é lido através de JPKI em vez de ICAO 9303 (`chip_protocol: "jpki"`), pelo que os riscos ICAO acima nunca são acionados para este documento. A sua leitura gera antes estes cinco riscos, cada um com a sua própria definição no nó de NFC: | Definição | Risco | Predefinição | | - | - | - | | `jpki_certificate_invalid_action` | `JPKI_CERTIFICATE_INVALID` | Recusar | | `jpki_signature_invalid_action` | `JPKI_SIGNATURE_INVALID` | Recusar | | `jpki_certificate_revoked_action` | `JPKI_CERTIFICATE_REVOKED` | Recusar | | `jpki_revocation_unchecked_action` | `JPKI_REVOCATION_UNCHECKED` | Revisão | | `jpki_inconsistent_data_action` | `JPKI_AND_OCR_DATA_NOT_SAME` | Revisão | Uma leitura ignorada do My Number Card gera `SKIPPED_NFC_VALIDATION` e segue `skip_nfc_action`, tal como qualquer chip. Consulte [Japan My Number Card (JPKI)](https://docs.didit.me/pt/core-technology/nfc-verification/overview.md#cartão-my-number-do-japão-jpki) para saber como funciona a leitura. > [!WARNING] > > A leitura de My Number Card através de JPKI ainda não está ativada em produção. Até que esteja ativada, um My Number Card ignora a etapa de NFC com o motivo para ignorar `JPKI_UNAVAILABLE` e nenhum destes riscos é gerado. ## Exemplos ### Em análise — não foi possível verificar o chip ```json theme={null} { "warnings": [ { "feature": "NFC", "risk": "NFC_CHIP_NOT_VERIFIED", "additional_data": null, "log_type": "warning", "short_description": "NFC chip not verified", "long_description": "The Near Field Communication (NFC) chip failed passive authentication for a reason other than an explicitly identified missing trust anchor. The chip data or signature could be invalid or altered.", "node_id": "nfc_primary" }, { "feature": "NFC", "risk": "DSC_CERTIFICATE_EXPIRED", "additional_data": null, "log_type": "information", "short_description": "Document Signer Certificate expired", "long_description": "The Document Signer Certificate (DSC) used to sign the ePassport chip data has expired, meaning the certificate's validity period has passed.", "node_id": "nfc_primary" } ] } ``` Aqui, a ação para chip não verificado está definida como Review, pelo que `NFC_CHIP_NOT_VERIFIED` apresenta `log_type: "warning"` e o estado do relatório de NFC é `In Review`. A entrada de DSC expirado é meramente informativa. ### Recusada — discrepância entre chip e OCR ```json theme={null} { "warnings": [ { "feature": "NFC", "risk": "NFC_AND_OCR_DATA_NOT_SAME", "additional_data": { "ocr_mrz": ["P