Relatório NFC: dados do chip e autenticidade

Visão geral

O relatório de verificação NFC registra o que a Didit leu e validou no chip NFC de um documento: um passaporte eletrônico, uma carteira de identidade eletrônica ou outro documento eletrônico ICAO 9303. Ele inclui os dados biográficos do chip, as verificações criptográficas de integridade (hashes do SOD e dos Data Groups) e um resumo do Document Signer Certificate (DSC) usado pelo país emissor. O relatório é gerado depois que o usuário conclui a etapa NFC de um fluxo de verificação (workflow). A Didit lê os Data Groups do chip no dispositivo do usuário, verifica a assinatura do Document Security Object (SOD) com o certificado CSCA do país emissor, confere o hash de cada Data Group com os valores assinados no SOD e compara a MRZ do chip com a MRZ extraída por OCR da face visível do documento. Um My Number Card japonês é lido por JPKI (chip_protocol: "jpki"): o relatório traz as verificações de certificado, assinatura, revogação e dados do titular em jpki, e os campos ICAO ficam null. Veja Japan My Number Card (JPKI). Cada relatório tem o próprio status, independente do status geral da sessão, que indica como a etapa NFC foi resolvida isoladamente:

Aprovado: o chip foi lido e nenhum dos avisos disparados está configurado para enviar a etapa para revisão ou recusa.
Em Revisão: pelo menos um aviso disparado tem a ação configurada como Revisão (por exemplo, NFC_CHIP_NOT_VERIFIED ou NFC_TRUST_ANCHOR_MISSING quando a ação para chip não verificado está definida como Revisão, ou JPKI_REVOCATION_UNCHECKED com a ação padrão).
Recusado: pelo menos um aviso disparado tem a ação configurada como Recusar (por exemplo, NFC_AND_OCR_DATA_NOT_SAME quando a ação para inconsistência de dados está definida como Recusar).
Not Finished: o usuário nunca concluiu a etapa NFC; a leitura do chip foi abandonada ou o dispositivo não oferecia suporte a NFC.
Resub Requested: um revisor pediu ao usuário que reenviasse; o relatório será substituído por uma nova tentativa.

Onde aparece nas respostas da API

O relatório NFC vem dentro do array nfc_verifications[], sempre um array JSON, nunca um objeto nfc único. Aparecem várias entradas quando um fluxo executa o NFC mais de uma vez (por exemplo, em um fluxo de autenticação adicional); cada entrada tem o próprio node_id.

API de decisão da sessão: aparece como nfc_verifications[] no nível superior de GET /v3/session/{sessionId}/decision/. Veja Retrieve session decision.
Webhooks: os payloads de status.updated incluem o mesmo array nfc_verifications[] assim que a etapa NFC gera dados. Veja Webhooks.
NFC avulso: para envio direto do chip, veja a visão geral de NFC.

Quando o seu fluxo inclui uma etapa NFC que foi pulada ou ignorada, o payload da decisão também traz o campo de nível superior nfc_skip_reason, que informa exatamente o motivo: o documento não tem chip, o certificado do país emissor não está disponível, o dispositivo não tem leitor NFC, a verificação foi feita sem SDK nativo (o navegador não tem acesso ao NFC), não foi possível derivar a chave de acesso do chip a partir da MRZ, não foi possível ler um My Number Card via JPKI ou o usuário optou por pular a etapa. Ele fica null para resultados fora dessa classificação, principalmente nos casos de um usuário que abandonou no meio da tentativa (status do relatório Not Finished) ou uma sessão em que o NFC ainda está pendente. Veja Motivos para pular para os valores exatos.

A documentação antiga fazia referência a um campo nfc único. Esse formato não existe no endpoint de decisão v3: ele só aparece em destinos explicitamente vinculados a webhooks V2, onde também traz chip_protocol e jpki. Sempre leia response.nfc_verifications[0] e percorra o array.

Schema

O schema canônico, campo a campo, está na página de referência Modelos de dados. Os campos abaixo espelham esse schema canônico.

Campo	Tipo	Descrição
`status`	`"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"`	Status da etapa NFC (veja os significados acima).
`node_id`	string \| null	Nó do grafo do fluxo de verificação (workflow) que gerou este relatório. Permite distinguir duas verificações NFC em um fluxo com várias etapas.
`is_nfc_skipped`	boolean	`true` quando esta etapa NFC foi pulada explicitamente em vez de o chip ser lido.
`skip_reason`	string \| null	Motivo pelo qual a etapa foi pulada. Só é preenchido quando `is_nfc_skipped` é `true`. Usa os mesmos valores de `nfc_skip_reason` no nível da sessão; veja Motivos para pular.
`chip_protocol`	`"icao"` \| `"jpki"`	Como o chip é lido. `icao`: um chip de passaporte eletrônico ou de eID em conformidade com ICAO 9303. `jpki`: um My Number Card japonês, cujo resultado fica em `jpki`; nesse caso, os campos ICAO abaixo (`portrait_image`, `signature_image`, `chip_data`, `authenticity`, `certificate_summary`) são `null`. Também é preenchido em etapas puladas.
`jpki`	object \| null	O que a leitura de um My Number Card comprovou; veja Campos JPKI. `null` para chips ICAO, para etapas puladas e quando a etapa foi encerrada sem nenhuma leitura de cartão.
`portrait_image`	string (URL assinada) \| null	Retrato extraído do chip (DG2). Link pré-assinado de curta duração: faça o download logo; consulte a decisão novamente para obter uma URL nova.
`signature_image`	string (URL assinada) \| null	Imagem da assinatura do titular extraída do chip (DG7), quando presente. Mesmo comportamento de link pré-assinado de curta duração.
`chip_data`	object \| null	Objeto plano com os dados biográficos extraídos do chip. Sempre presente após uma leitura bem-sucedida: `dgs` (lista dos Data Groups lidos), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (código de documento da MRZ, por exemplo `P`), `document_number`, `optional_data`, os dígitos verificadores da MRZ (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string` e `mrz_type` (`TD1`/`TD2`/`TD3`). Quando o chip contém o DG11, são adicionados `place_of_birth` e `address` (e `full_name` / `full_name_non_latin` para documentos com nome em sistema de escrita não latino); caso contrário, essas chaves ficam ausentes, não null. `null` quando a etapa NFC foi pulada.
`authenticity`	object \| null	Resultados da autenticação passiva ICAO, descritos abaixo. `null` para uma leitura JPKI.
`authenticity.sod_integrity`	boolean	`true` quando a assinatura do SOD forma uma cadeia até uma CSCA válida do país emissor e o DSC não está revogado nem expirado.
`authenticity.dg_integrity`	boolean	`true` quando o hash de cada Data Group corresponde ao valor assinado pelo SOD. Um valor `false` significa que os dados do chip foram adulterados ou lidos parcialmente.
`certificate_summary`	object \| null	Resumo do DSC que assinou este chip: `issuer`, `subject`, `serial_number`, `not_valid_before`, `not_valid_after` (timestamps no formato `YYYY-MM-DD HH:MM:SS`), além de um objeto `validation` com os resultados de cada verificação (`csca_verified`, `csca_missing`, `dsc_revoked`, `dsc_expired`, `csca_expired`). `csca_missing` é `true` quando a âncora de confiança CSCA emissora do DSC não está disponível. `null` quando o SOD não pôde ser carregado ou a etapa foi pulada.
`warnings[]`	array	Avisos do módulo, cada um com `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description` e `node_id`. Veja Avisos de NFC.

Valores de status

Status	Significado	Efeito posterior
`Approved`	O chip foi lido e nenhum aviso com ação de revisão ou recusa foi disparado, incluindo o caso em que avisos foram disparados, mas a ação configurada para eles é “Nenhuma ação”.	Conta como uma verificação NFC bem-sucedida; por si só, não leva a sessão para revisão.
`In Review`	Foi disparado um aviso cuja ação configurada é revisão (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME` ou um dos avisos `JPKI_*`, conforme as suas configurações).	A sessão também passa para `In Review` até que um revisor atue.
`Declined`	Foi disparado um aviso cuja ação configurada é recusa.	A sessão é recusada, a menos que outra ramificação aprovada satisfaça o fluxo.
`Not Finished`	O usuário abandonou a etapa NFC, o dispositivo não tinha suporte a NFC ou a leitura do chip não foi concluída.	A ramificação NFC não gerou um resultado; verifique as fallbacks do fluxo.
`Resub Requested`	Um revisor solicitou o reenvio desta etapa.	Uma nova tentativa substitui este relatório quando o usuário tentar novamente.

Os dois avisos de certificado (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) são informativos: aparecem em warnings[], mas nunca alteram o status do NFC por si só. Veja Avisos de NFC para a matriz completa de comportamento.

Exemplos

Aprovado: chip lido e criptograficamente válido

{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": "https://<media-host>/.../epassport/<session-id>_signature.jpg?signature=...",
      "chip_data": {
        "dgs": ["DG1", "DG2", "DG7", "DG11"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000123",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "3",
        "optional_data_hash": "",
        "final_hash": "4",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04",
        "mrz_type": "TD3",
        "place_of_birth": "MADRID, MADRID",
        "address": "CALLE MAYOR 1, MADRID"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": []
    }
  ]
}

Recusado: divergência entre OCR e chip

{
  "nfc_verifications": [
    {
      "status": "Declined",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": null,
      "chip_data": {
        "dgs": ["DG1", "DG2"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000254",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "6",
        "optional_data_hash": "",
        "final_hash": "6",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06",
        "mrz_type": "TD3"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "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"
        }
      ]
    }
  ]
}

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

Nos SDKs nativos, o Cartão My Number do Japão é lido via JPKI: a pessoa digita o PIN do cartão e o cartão assina um desafio de uso único (veja como funciona). O relatório tem chip_protocol: "jpki" e traz as evidências em jpki. portrait_image, signature_image, chip_data, authenticity e certificate_summary são null, porque o cartão não contém dados ICAO.

A leitura do Cartão My Number via JPKI ainda não está habilitada em produção. Até que esteja, o Cartão My Number pula a etapa NFC com o motivo JPKI_UNAVAILABLE.

Campos JPKI

Campo	Tipo	Descrição
`jpki.certificate_types`	array de `"user_authentication"` \| `"signature"`	Os certificados do cartão que foram lidos. `user_authentication` (PIN de 4 dígitos) é sempre lido. `signature` (PIN de assinatura) é lido quando a configuração `jpki_request_attributes` do nó NFC está ativada, o que é o padrão.
`jpki.chain_valid`	boolean	`true` quando cada certificado se encadeia à autoridade certificadora JPKI do seu tipo, está dentro do período de validade e é um certificado de Cartão My Number desse tipo.
`jpki.signature_valid`	boolean	`true` quando cada assinatura que o cartão gerou sobre o desafio de uso único é verificada com sucesso. O cartão só assina depois que o PIN é digitado, então isso comprova que a pessoa tem o cartão em mãos e sabe o PIN.
`jpki.revocation_status`	`"good"` \| `"revoked"` \| `"unchecked"`	`good`: todos os certificados foram confirmados como não revogados. `revoked`: um certificado foi revogado, por exemplo porque o cartão foi declarado perdido. `unchecked`: nenhuma resposta sobre revogação estava disponível, então não é possível descartar um cartão revogado. Esse valor nunca é tratado como `good`. A revogação só é verificada depois que a cadeia e a assinatura são válidas.
`jpki.ca_generation`	string \| null	Geração da autoridade certificadora JPKI que emitiu os certificados, por exemplo `"2023"`. É `null` quando nenhum certificado se encadeia a uma delas.
`jpki.certificate_expires_at`	string (ISO 8601) \| null	A data de validade mais próxima entre os certificados lidos.
`jpki.certificates[]`	array	Uma entrada por certificado lido: `type`, `chain_valid`, `signature_valid`, `ca_generation`, `not_valid_before`, `not_valid_after` e `failure`. `failure` é `null` quando a cadeia é válida. Caso contrário, é um destes valores: `unreadable_certificate`, `untrusted_issuer`, `expired`, `not_yet_valid`, `wrong_policy` (não é um certificado de Cartão My Number desse tipo) ou `key_usage`.
`jpki.attributes`	object \| null	Os dados do titular obtidos do certificado de assinatura, depois que a cadeia dele é validada. Os campos são `full_name` (como registrado, geralmente em escrita japonesa), `date_of_birth` (`YYYY-MM-DD`), `gender` (`M`, `F` ou `null`) e `address`. Há também `name_substitute_characters` / `address_substitute_characters`, que indicam caracteres trocados por um substituto por estarem fora do conjunto de caracteres padrão (`null` quando nenhum foi trocado). É `null` quando o certificado de assinatura não foi solicitado ou quando a cadeia dele não é válida.
`jpki.attributes_match_ocr`	boolean \| null	`true` quando os atributos correspondem aos dados lidos na foto do mesmo cartão. `false` quando algum deles é diferente (`JPKI_AND_OCR_DATA_NOT_SAME`). `null` quando nada pôde ser comparado, inclusive sempre que `attributes` é `null`.
`jpki.mismatched_attributes`	array de string	Os atributos que diferem dos dados da foto (`full_name`, `date_of_birth`, `gender`, `address`), nunca os valores deles.

O relatório nunca inclui os próprios certificados, os números de série deles, as assinaturas nem o Número Individual (My Number) de 12 dígitos do cartão, que a etapa NFC nunca lê.

Exemplo: leitura do Cartão My Number

{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": null,
      "signature_image": null,
      "chip_data": null,
      "is_nfc_skipped": false,
      "skip_reason": null,
      "chip_protocol": "jpki",
      "jpki": {
        "certificate_types": ["user_authentication", "signature"],
        "chain_valid": true,
        "signature_valid": true,
        "revocation_status": "good",
        "ca_generation": "2023",
        "certificate_expires_at": "2029-05-15T14:59:59Z",
        "certificates": [
          {
            "type": "user_authentication",
            "chain_valid": true,
            "signature_valid": true,
            "ca_generation": "2023",
            "not_valid_before": "2024-06-03T01:12:40+00:00",
            "not_valid_after": "2029-05-15T14:59:59+00:00",
            "failure": null
          },
          {
            "type": "signature",
            "chain_valid": true,
            "signature_valid": true,
            "ca_generation": "2023",
            "not_valid_before": "2024-06-03T01:12:40+00:00",
            "not_valid_after": "2029-05-15T14:59:59+00:00",
            "failure": null
          }
        ],
        "attributes": {
          "full_name": "山田 太郎",
          "date_of_birth": "1990-05-15",
          "gender": "M",
          "address": "東京都千代田区千代田1番1号",
          "name_substitute_characters": null,
          "address_substitute_characters": null
        },
        "attributes_match_ocr": true,
        "mismatched_attributes": []
      },
      "authenticity": null,
      "certificate_summary": null,
      "warnings": []
    }
  ]
}

Quando a verificação de revogação não está disponível em uma leitura, o mesmo relatório tem revocation_status: "unchecked" e um aviso JPKI_REVOCATION_UNCHECKED. Com as configurações padrão, ele também tem status: "In Review". Veja Avisos de NFC.

Nota de segurança

Os dados do chip NFC são assinados pela autoridade emissora. Por isso, um relatório aprovado com sod_integrity: true e dg_integrity: true é a evidência de identidade mais forte que a Didit pode produzir. Trate as URLs assinadas das imagens (portrait_image, signature_image) como temporárias: faça o download delas logo e não as armazene em cache público. Solicite a decisão novamente quando precisar de links novos.

Relacionados

Avisos de NFC: enum completo de avisos, causas e soluções.
Webhooks: ouça o evento status.updated para receber o relatório NFC.
Modelos de dados: verificação NFC: schema canônico com todos os campos.
Documentos compatíveis: quais documentos eletrônicos a Didit consegue ler via NFC.

Autenticação

Verificação

Monitoramento

Plataforma

Relatório NFC: dados do chip e autenticidade

Visão geral

Onde aparece nas respostas da API

Schema

Valores de status

Exemplos

Aprovado: chip lido e criptograficamente válido

Recusado: divergência entre OCR e chip

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

Campos JPKI

Exemplo: leitura do Cartão My Number

Nota de segurança

Relacionados

​Visão geral

​Onde aparece nas respostas da API

​Schema

​Valores de status

​Exemplos

​Aprovado: chip lido e criptograficamente válido

​Recusado: divergência entre OCR e chip

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

​Campos JPKI

​Exemplo: leitura do Cartão My Number

​Nota de segurança

​Relacionados

Visão geral

Onde aparece nas respostas da API

Schema

Valores de status

Exemplos

Aprovado: chip lido e criptograficamente válido

Recusado: divergência entre OCR e chip

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

Campos JPKI

Exemplo: leitura do Cartão My Number

Nota de segurança

Relacionados