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

Visão geral

Os avisos no relatório de NFC sinalizam cada condição que a Didit observou ao ler e validar o chip. Eles ficam no array warnings[] de cada item de nfc_verifications[] (consulte o relatório de NFC), com feature definido como "NFC". Cada entrada segue o formato compartilhado do objeto de aviso: feature, risk, additional_data, log_type, short_description, long_description, node_id. Todo aviso tem três camadas:

O código risk: um identificador estável que você pode usar para correspondência no seu código (os códigos listados abaixo).
O log_type: um entre information, warning ou error. Ele é derivado da ação que o seu fluxo configura para esse risco: No action → information, Review → warning, Decline → 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 o move para In Review, e uma ação de Recusar, para Declined.

Quatro riscos de NFC são configuráveis dessa forma (SKIPPED_NFC_VALIDATION, NFC_CHIP_NOT_VERIFIED, NFC_TRUST_ANCHOR_MISSING, NFC_AND_OCR_DATA_NOT_SAME), além dos cinco riscos do My Number Card do Japão, cada um com sua própria configuração. Os dois riscos de certificado (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) são apenas informativos: eles sempre têm log_type: "information" e nunca alteram o status de NFC por si só. O conjunto completo de códigos de risco que o módulo de NFC produz está abaixo. Não existe nenhum outro código de risco de NFC.

Avisos gerados

`risk`	Causa	Gravidade (`log_type`)	Afeta o status?	Correção
`SKIPPED_NFC_VALIDATION`	A leitura do chip foi pulada: o fluxo permite pular essa etapa (`allow_nfc_skip`) e o usuário tocou em pular, ou o cliente pulou porque não conseguiu ler o NFC. O motivo exato é registrado em `additional_data.skip_reason` (veja Motivos para pular) e determina o `long_description` do aviso.	Segue a configuração skip NFC action (`skip_nfc_action`): informação / aviso / erro.	Configurável: Nenhuma ação, Revisar ou Recusar.	Se a sua política exige NFC, defina a ação de pular como Recusar (ou não permita pular) e oriente o usuário a tentar novamente em um dispositivo com NFC. Caso contrário, mantenha em Nenhuma ação para recorrer à verificação apenas por OCR.
`NFC_CHIP_NOT_VERIFIED`	O chip foi lido, mas falhou na verificação criptográfica por um motivo diferente da ausência, identificada explicitamente, de uma âncora de confiança. Um hash de Data Group, a assinatura do SOD ou outra verificação de autenticação passiva não foi validada.	Segue a configuração unverified chip action (`unverified_chip_action`).	Configurável: Nenhuma ação, Revisar ou Recusar.	Trate como um chip possivelmente inválido ou alterado. 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`). Por isso, a Didit não consegue estabelecer a cadeia de confiança do SOD.	Segue a configuração unverified chip action (`unverified_chip_action`).	Configurável: Nenhuma ação, Revisar ou Recusar.	Trata-se de uma lacuna de cobertura do repositório de confiança, não de evidência de que o chip foi alterado. Revise o documento com as suas verificações alternativas e entre em contato com o suporte da Didit informando o país emissor, para que a CSCA ausente seja investigada.
`NFC_AND_OCR_DATA_NOT_SAME`	A MRZ lida do chip não corresponde à MRZ extraída por OCR do lado visível do documento (a comparação é feita após a normalização, ignorando o caractere de preenchimento `<`). Forte sinal de adulteração.	Segue a configuração data inconsistency action (`inconsistent_data_action`), a mesma que rege as verificações de consistência de dados da verificação de identidade.	Configurável: Nenhuma ação, Revisar ou Recusar.	Trate como adulteração, salvo prova em contrário; Recusar é a configuração mais comum. O payload `additional_data` inclui as linhas da MRZ obtidas por 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 consta na Certificate Revocation List (CRL) do país emissor.	Sempre `information`.	Não: nunca altera o status do NFC por si só.	Forte sinal de que a chave de assinatura pode ter sido comprometida; se necessário, encaminhe essas sessões para revisão manual com a sua própria lógica. Observe que o chip normalmente também dispara `NFC_CHIP_NOT_VERIFIED`, que é configurável.
`DSC_CERTIFICATE_EXPIRED`	O período de validade do DSC terminou (`certificate_summary.validation.dsc_expired` é `true`).	Sempre `information`.	Não: nunca altera o status do NFC por si só.	Comum em documentos mais antigos. Assim como na revogação, um DSC expirado também falha na validação completa do SOD, então `NFC_CHIP_NOT_VERIFIED` é disparado junto e aplica a ação que você configurou.
`JPKI_CERTIFICATE_INVALID`	My Number Card do Japão: um certificado lido do cartão não se encadeia à autoridade certificadora JPKI do seu tipo, está fora do período de validade ou não é um certificado de My Number Card desse tipo. `additional_data.certificate_types` lista os certificados que falharam; `jpki.certificates[].failure` informa o motivo.	Segue `jpki_certificate_invalid_action` (padrão: Recusar).	Configurável: Nenhuma ação, Revisar ou Recusar.	Trate como um cartão inválido ou alterado. Um certificado do cartão expirado também cai aqui: o titular o renova na prefeitura do seu município.
`JPKI_SIGNATURE_INVALID`	My Number Card do Japão: a assinatura do cartão sobre o desafio de uso único não é validada com o certificado correspondente, então a posse do cartão e o conhecimento do PIN não ficam comprovados. Também é gerado quando a etapa de NFC foi encerrada sem nenhuma leitura do cartão (nesse caso, `additional_data.certificate_types` fica vazio).	Segue `jpki_signature_invalid_action` (padrão: Recusar).	Configurável: Nenhuma ação, Revisar ou Recusar.	Não aceite a leitura do cartão como prova. Peça à pessoa que tente novamente com o cartão físico.
`JPKI_CERTIFICATE_REVOKED`	My Number Card do Japão: a verificação de revogação informa que um certificado foi revogado, por exemplo porque o cartão foi declarado perdido ou o cadastro do titular mudou (`jpki.revocation_status` é `revoked`).	Segue `jpki_certificate_revoked_action` (padrão: Recusar).	Configurável: Nenhuma ação, Revisar ou Recusar.	Não aceite o cartão.
`JPKI_REVOCATION_UNCHECKED`	My Number Card do Japão: os certificados e a assinatura foram verificados, mas nenhuma resposta sobre revogação estava disponível (`jpki.revocation_status` é `unchecked`), então não é possível descartar que o cartão esteja revogado. Não é gerado quando a cadeia ou a assinatura já falharam.	Segue `jpki_revocation_unchecked_action` (padrão: Revisar).	Configurável: Nenhuma ação, Revisar ou Recusar.	Decida quanto vale para você um cartão verificado sem resposta sobre revogação e defina a ação de acordo.
`JPKI_AND_OCR_DATA_NOT_SAME`	My Number Card do Japão: o nome, a data de nascimento, o sexo ou o endereço no certificado de assinatura diferem dos dados lidos da foto do mesmo cartão. `additional_data.fields` indica os atributos que diferem, nunca os seus valores.	Segue `jpki_inconsistent_data_action` (padrão: Revisar).	Configurável: Nenhuma ação, Revisar ou Recusar.	Compare `jpki.attributes` com os dados da verificação de identidade antes de decidir. Um nome com um caractere incomum pode diferir porque o certificado contém um caractere 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 entre si.

Textos de descrição exatos

A API retorna exatamente estes textos de short_description e long_description para cada risco:

`risk`	`short_description`	`long_description`
`SKIPPED_NFC_VALIDATION`	Skipped NFC Validation	Depende do motivo: consulte Motivos de omissão. Em sessões legadas, registradas antes da existência dos motivos de omissão, o texto padrão é “O processo de validação do chip Near Field Communication (NFC) não foi concluído, possivelmente devido a problemas técnicos ou à falta de suporte a NFC.”
`NFC_CHIP_NOT_VERIFIED`	NFC chip not verified	O chip Near Field Communication (NFC) falhou na autenticação passiva por um motivo que não é a ausência de uma âncora de confiança identificada explicitamente. Os dados ou a assinatura do chip podem ser inválidos ou ter sido alterados.
`NFC_TRUST_ANCHOR_MISSING`	NFC trust anchor unavailable	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 lacuna de cobertura do repositório de confiança, e não de uma evidência de que o chip foi alterado.
`NFC_AND_OCR_DATA_NOT_SAME`	NFC and OCR data not same	Os dados do chip Near Field Communication (NFC) e os dados de OCR não coincidem, o que indica uma possível adulteração do documento ou inconsistência de dados.
`DSC_CERTIFICATE_REVOKED`	Document Signer Certificate revoked	O Document Signer Certificate (DSC) usado para assinar os dados do chip do passaporte eletrônico foi revogado pela Certificate Revocation List (CRL) do país emissor, o que indica que a chave de assinatura pode ter sido comprometida.
`DSC_CERTIFICATE_EXPIRED`	Document Signer Certificate expired	O Document Signer Certificate (DSC) usado para assinar os dados do chip do passaporte eletrônico expirou, ou seja, o período de validade do certificado já passou.
`JPKI_CERTIFICATE_INVALID`	My Number Card certificate not valid	Um certificado lido do chip do My Number Card não é válido: ele não se encadeia à autoridade certificadora 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`	My Number Card signature not valid	A assinatura que o My Number Card gerou para o desafio de verificação de uso único não pode ser verificada com base no certificado do cartão, portanto a posse do cartão e o conhecimento do seu PIN não estão comprovados.
`JPKI_CERTIFICATE_REVOKED`	My Number Card certificate revoked	A verificação de revogação informa que um certificado lido do My Number Card foi revogado, por exemplo porque o cartão foi declarado perdido ou porque o cadastro do titular mudou.
`JPKI_REVOCATION_UNCHECKED`	My Number Card revocation status not checked	O certificado e a assinatura do My Number Card foram verificados, mas não foi possível verificar o status de revogação, portanto não é possível descartar que o cartão tenha sido revogado.
`JPKI_AND_OCR_DATA_NOT_SAME`	My Number Card chip and OCR data not same	O nome, a data de nascimento, o sexo ou o endereço 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 de omissão

Os avisos SKIPPED_NFC_VALIDATION trazem additional_data.skip_reason, um entre sete códigos estáveis que informam exatamente por que o NFC não foi executado. Em sessões registradas antes da existência dos motivos de omissão, additional_data pode ser null, por isso trate o campo como opcional ao processar decisões históricas. A mesma classificação aparece no nível da sessão como nfc_skip_reason no payload da decisão. Isso vale também para sessões em que o NFC nunca poderia ser executado (documento sem chip, integração web) e em que, portanto, não existe relatório nem aviso de NFC.

`skip_reason`	Significado	`long_description`
`USER_SKIPPED`	O NFC foi oferecido em um dispositivo compatível e o usuário optou por pular a etapa.	A etapa de leitura do chip NFC foi oferecida em um dispositivo compatível, mas o usuário optou por pulá-la (a configuração do fluxo permite pular).
`DOCUMENT_WITHOUT_CHIP`	O modelo do documento não tem 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: ele não é um documento eletrônico ICAO 9303.
`CHIP_CERTIFICATE_UNAVAILABLE`	O chip existe, mas nenhum certificado de assinatura do país emissor (CSCA) cobre o período de emissão do documento, então 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 cobre o período de emissão deste documento não está disponível, então a assinatura do chip não pode ser verificada.
`DEVICE_WITHOUT_NFC`	Um SDK nativo informou que o celular não tem leitor NFC disponível.	Não foi possível realizar a verificação NFC porque o dispositivo do usuário informou que não tem leitor NFC disponível.
`INTEGRATION_WITHOUT_NFC_ACCESS`	A verificação foi executada sem um SDK nativo (por exemplo, em um navegador web), que não tem acesso ao leitor NFC do celular.	Não foi possível realizar a verificação NFC porque a verificação não foi executada por meio de um SDK móvel nativo, então não houve acesso ao leitor NFC do celular (navegadores web não conseguem ler chips NFC).
`MRZ_KEY_UNAVAILABLE`	Não foi possível derivar a chave de acesso ao chip (semente BAC/PACE) 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 da zona de leitura óptica (MRZ) do documento.
`JPKI_UNAVAILABLE`	O documento é um Cartão My Number do Japão, cujo chip é lido por meio do JPKI, e o JPKI não estava disponível para esta verificação: ele não está habilitado ou a versão do SDK nativo do app não consegue ler Cartões My Number. Um Cartão My Number verificado em um navegador recebe `INTEGRATION_WITHOUT_NFC_ACCESS`, e um em um celular sem NFC recebe `DEVICE_WITHOUT_NFC`, como qualquer chip.	Não foi possível realizar a verificação NFC porque este Cartão My Number é lido por meio do JPKI, que não estava disponível para esta verificação: ele não está habilitado ou o SDK do app não consegue ler Cartões My Number.

Um relatório de NFC e seu aviso SKIPPED_NFC_VALIDATION só existem quando o cliente chegou à etapa de NFC e a pulou explicitamente (normalmente USER_SKIPPED, ou DEVICE_WITHOUT_NFC quando o leitor se revelou indisponível no momento da leitura). Quando a etapa de NFC foi ignorada antes de poder ser oferecida (documento sem chip, certificado ausente, nenhuma capacidade NFC informada, chave da MRZ ilegível, JPKI indisponível), nenhum relatório ou aviso é criado e o motivo aparece apenas no campo nfc_skip_reason no nível da sessão, sem afetar o status da sessão.

Configuração

Três configurações do fluxo controlam como os avisos de NFC são encaminhados. Cada uma pode ser definida como Sem ação, Revisão ou Recusar:

Skip NFC action (skip_nfc_action): aplica-se a SKIPPED_NFC_VALIDATION. A opção de pular só é oferecida aos usuários quando allow_nfc_skip está habilitado.
Unverified chip action (unverified_chip_action): aplica-se tanto a NFC_CHIP_NOT_VERIFIED quanto a NFC_TRUST_ANCHOR_MISSING, de modo que o comportamento do status da sessão continua o mesmo, enquanto o código de risco explica por que a verificação falhou.
Data inconsistency action (inconsistent_data_action): aplica-se a NFC_AND_OCR_DATA_NOT_SAME. É a mesma configuração de inconsistência de dados usada pela verificação de identidade.

Os dois riscos DSC_CERTIFICATE_* não têm configuração de ação: são sempre informativos. Os riscos do Cartão My Number do Japão têm mais cinco configurações, listadas na próxima seção.

Cartão My Number do Japão (JPKI)

Um Cartão My Number do Japão é lido por meio do JPKI em vez do ICAO 9303 (chip_protocol: "jpki"), então os riscos ICAO acima nunca são disparados para ele. Em vez disso, sua leitura gera estes cinco riscos, cada um com sua própria configuração no nó de NFC:

Configuração	Risco	Padrã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 Cartão My Number gera SKIPPED_NFC_VALIDATION e segue skip_nfc_action, como qualquer chip. Consulte Cartão My Number do Japão (JPKI) para saber como a leitura funciona.

A leitura do Cartão My Number por meio do JPKI ainda não está habilitada em produção. Até que esteja, um Cartão My Number pula a etapa de NFC com o motivo de omissão JPKI_UNAVAILABLE e nenhum desses riscos é gerado.

Exemplos

Em revisão: 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, então NFC_CHIP_NOT_VERIFIED traz log_type: "warning" e o status do relatório NFC é In Review. A entrada de DSC expirado é apenas informativa.

Recusado: divergê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, então o aviso traz log_type: "error" e o status do relatório NFC é Declined. Observe que ocr_mrz é um array de linhas da MRZ, enquanto nfc_mrz é a string única e concatenada da MRZ do chip.

Em revisão: 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 seu padrão, Review, então o aviso traz log_type: "warning" e o status do relatório NFC é In Review. A autenticidade do cartão foi comprovada: jpki.chain_valid e jpki.signature_valid são ambos true.

Tipos de aviso

Cada risco recebe um nível de severidade com base na configuração da sua aplicação. As três severidades são:

Relacionados

Relatório NFC: esquema completo do relatório e status.
Webhooks: status.updated é disparado quando o status da sessão muda; o payload da decisão (incluindo os avisos de NFC) é anexado quando a sessão chega a Approved, Declined, In Review ou Abandoned.
Modelos de dados: Verificação NFC: esquema canônico, campo por campo.
Modelos de dados: Objeto de aviso: o formato de cada entrada em warnings[].

Autenticação

Verificação

Monitoramento

Plataforma

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

Visão geral

Avisos gerados

Textos de descrição exatos

Motivos de omissão

Configuração

Cartão My Number do Japão (JPKI)

Exemplos

Em revisão: não foi possível verificar o chip

Recusado: divergência entre chip e OCR

Em revisão: My Number Card sem resposta de revogação

Tipos de aviso

Relacionados

​Visão geral

​Avisos gerados

​Textos de descrição exatos

​Motivos de omissão

​Configuração

​Cartão My Number do Japão (JPKI)

​Exemplos

​Em revisão: não foi possível verificar o chip

​Recusado: divergência entre chip e OCR

​Em revisão: My Number Card sem resposta de revogação

​Tipos de aviso

​Relacionados

Visão geral

Avisos gerados

Textos de descrição exatos

Motivos de omissão

Configuração

Cartão My Number do Japão (JPKI)

Exemplos

Em revisão: não foi possível verificar o chip

Recusado: divergência entre chip e OCR

Em revisão: My Number Card sem resposta de revogação

Tipos de aviso

Relacionados