> ## 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. # Relatório NFC: dados do chip e autenticidade > Como ler o relatório NFC / ePassport da Didit: status, dados do chip, autenticidade do certificado, local nas respostas da API e payloads. ## 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)](#cartão-my-number-do-japão-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](https://docs.didit.me/pt-br/sessions-api/retrieve-session.md). * **Webhooks**: os payloads de `status.updated` incluem o mesmo array `nfc_verifications[]` assim que a etapa NFC gera dados. Veja [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md). * **NFC avulso**: para envio direto do chip, veja a [visão geral de NFC](https://docs.didit.me/pt-br/core-technology/nfc-verification/overview.md). 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](https://docs.didit.me/pt-br/core-technology/nfc-verification/warnings-nfc-verification.md#motivos-de-omissão) para os valores exatos. > [!NOTE] > > 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](https://docs.didit.me/pt-br/reference/data-models.md#verificação-nfc). 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](https://docs.didit.me/pt-br/core-technology/nfc-verification/warnings-nfc-verification.md#motivos-de-omissão). | | `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](#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](https://docs.didit.me/pt-br/core-technology/nfc-verification/warnings-nfc-verification.md). | ## 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. | > [!NOTE] > > 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](https://docs.didit.me/pt-br/core-technology/nfc-verification/warnings-nfc-verification.md) para a matriz completa de comportamento. ## Exemplos ### Aprovado: chip lido e criptograficamente válido ```json theme={null} { "nfc_verifications": [ { "status": "Approved", "node_id": "nfc_primary", "portrait_image": "https:///.../epassport/_face.jpg?signature=...", "signature_image": "https:///.../epassport/_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/.../epassport/_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 [!WARNING] > > 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 ```json theme={null} { "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](https://docs.didit.me/pt-br/core-technology/nfc-verification/warnings-nfc-verification.md#cartão-my-number-do-japão-jpki). ## 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](https://docs.didit.me/pt-br/core-technology/nfc-verification/warnings-nfc-verification.md): enum completo de avisos, causas e soluções. * [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md): ouça o evento `status.updated` para receber o relatório NFC. * [Modelos de dados: verificação NFC](https://docs.didit.me/pt-br/reference/data-models.md#verificação-nfc): schema canônico com todos os campos. * [Documentos compatíveis](https://docs.didit.me/pt-br/core-technology/nfc-verification/supported-documents-nfc-verification.md): quais documentos eletrônicos a Didit consegue ler via NFC. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.