Avisos e códigos de erro da verificação NFC

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), com feature definido como "NFC". Cada entrada segue o formato partilhado do objeto de aviso: feature, risk, additional_data, log_type, short_description, long_description, node_id. Cada aviso tem três camadas:

O código risk — um identificador estável que pode usar para fazer correspondência no seu código (os códigos listados abaixo).
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.
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, 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) 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`).

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. 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.

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:

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.
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.
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) para saber como funciona a leitura.

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

{
  "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

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "NFC_AND_OCR_DATA_NOT_SAME",
    "additional_data": {
      "ocr_mrz": ["P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<", "AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04"],
      "nfc_mrz": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06"
    },
    "log_type": "error",
    "short_description": "NFC and OCR data not same",
    "long_description": "The Near Field Communication (NFC) chip data and the OCR data don't match, indicating potential document tampering or data inconsistency.",
    "node_id": "nfc_primary"
  }
]
}

Aqui, a ação para inconsistência de dados está definida como Decline, pelo que o aviso apresenta log_type: "error" e o estado do relatório de NFC é Declined. Note que ocr_mrz é um array de linhas MRZ, enquanto nfc_mrz é a string MRZ única concatenada do chip.

Em análise: My Number Card sem resposta de revogação

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "JPKI_REVOCATION_UNCHECKED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "My Number Card revocation status not checked",
    "long_description": "The certificate and signature of the My Number Card were verified, but its revocation status could not be checked, so a revoked card cannot be ruled out.",
    "node_id": "nfc_primary"
  }
]
}

Aqui, jpki_revocation_unchecked_action mantém o seu valor predefinido, Review, pelo que o aviso apresenta log_type: "warning" e o estado do relatório de NFC é In Review. A autenticidade do próprio cartão foi comprovada: jpki.chain_valid e jpki.signature_valid são ambos true.

Tipos de aviso

A cada risco é atribuída uma gravidade com base na configuração da sua aplicação. As três gravidades são:

Conteúdo relacionado

Relatório de NFC — esquema completo e estados do relatório.
Webhooks — o evento status.updated é acionado em alterações de estado da sessão; o payload de decisão (incluindo avisos de NFC) é anexado quando a sessão atinge Approved, Declined, In Review ou Abandoned.
Modelos de dados — Verificação NFC — esquema canónico campo a campo.
Modelos de dados — Objeto Warning — a estrutura de cada entrada em warnings[].

Autenticação

Verificação

Monitorização

Plataforma

Avisos e códigos de erro da verificação NFC

Visão geral

Avisos gerados

Strings de descrição exatas

Motivos para ignorar

Configuração

Japan My Number Card (JPKI)

Exemplos

Em análise — não foi possível verificar o chip

Recusada — discrepância entre chip e OCR

Em análise: My Number Card sem resposta de revogação

Tipos de aviso

Conteúdo relacionado

​Visão geral

​Avisos gerados

​Strings de descrição exatas

​Motivos para ignorar

​Configuração

​Japan My Number Card (JPKI)

​Exemplos

​Em análise — não foi possível verificar o chip

​Recusada — discrepância entre chip e OCR

​Em análise: My Number Card sem resposta de revogação

​Tipos de aviso

​Conteúdo relacionado

Visão geral

Avisos gerados

Strings de descrição exatas

Motivos para ignorar

Configuração

Japan My Number Card (JPKI)

Exemplos

Em análise — não foi possível verificar o chip

Recusada — discrepância entre chip e OCR

Em análise: My Number Card sem resposta de revogação

Tipos de aviso

Conteúdo relacionado