> ## 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. # Verificação NFC: relatório de chip e autenticidade > Aprenda a ler o relatório de verificação NFC da Didit: estado, dados do chip, autenticidade do certificado e payloads de resposta da API. ## Visão geral O **relatório de verificação NFC** regista o que a Didit leu e validou a partir do chip NFC de um documento — um passaporte eletrónico, um cartão de identificação eletrónico ou outro documento eletrónico em conformidade com a ICAO 9303. Inclui os dados biográficos do chip, as verificações de integridade criptográfica (hashes de SOD e de Data Groups) e um resumo do Document Signer Certificate (DSC) utilizado pelo país emissor. O relatório é gerado após o utilizador concluir o passo de NFC num fluxo. A Didit lê os Data Groups do chip no dispositivo do utilizador, verifica a assinatura do Document Security Object (SOD) em relação ao certificado CSCA do país emissor, verifica cada hash de Data Group relativamente aos valores assinados pelo SOD e cruza a MRZ do chip com a MRZ obtida por OCR da parte visível do documento. O cartão japonês My Number Card é lido, em alternativa, através de JPKI (`chip_protocol: "jpki"`): o respetivo relatório apresenta as verificações de certificado, assinatura, revogação e dados do titular sob `jpki`, e os campos ICAO permanecem `null`. Consulte [Japan My Number Card (JPKI)](#cartão-my-number-do-japão-jpki). Cada relatório tem o seu próprio `status` — independente do estado geral da sessão — que reflete o desfecho exclusivo do passo de NFC: * **Aprovada** — o chip foi lido e nenhum dos avisos acionados está configurado para encaminhar o passo para revisão ou recusa. * **Em análise** — foi acionado pelo menos um aviso cuja ação configurada é **Revisão** (por exemplo, `NFC_CHIP_NOT_VERIFIED` ou `NFC_TRUST_ANCHOR_MISSING` quando a ação para chip não verificado está definida para Revisão, ou `JPKI_REVOCATION_UNCHECKED` com a sua ação predefinida). * **Recusada** — foi acionado pelo menos um aviso cuja ação configurada é **Recusar** (por exemplo, `NFC_AND_OCR_DATA_NOT_SAME` quando a ação para inconsistência de dados está definida para Recusar). * **Não concluído** — o utilizador nunca concluiu o passo de NFC; a leitura do chip foi abandonada ou o dispositivo não suportava NFC. * **Nova submissão solicitada** — um revisor solicitou ao utilizador que submetesse novamente; o relatório será substituído por uma nova tentativa. ## Onde surge nas respostas da API O relatório de NFC é fornecido dentro do array `nfc_verifications[]` — **sempre um array JSON**, nunca um objeto `nfc` singular. Surgem várias entradas quando um fluxo executa NFC mais do que uma vez (por exemplo, num fluxo de step-up); cada entrada inclui o seu próprio `node_id`. * **API de decisão da sessão** — surge como `nfc_verifications[]` no nível raiz de `GET /v3/session/{sessionId}/decision/`. Consulte [Obter decisão da sessão](https://docs.didit.me/pt/sessions-api/retrieve-session.md). * **Webhooks** — os payloads de `status.updated` incluem o mesmo array `nfc_verifications[]` assim que o passo de NFC produzir dados. Consulte [Webhooks](https://docs.didit.me/pt/integration/webhooks.md). * **NFC autónomo** — para submissão direta do chip, consulte a [visão geral de NFC](https://docs.didit.me/pt/core-technology/nfc-verification/overview.md). Quando o seu fluxo inclui um passo de NFC que foi ignorado ou contornado, o payload de decisão inclui também um campo `nfc_skip_reason` no nível raiz que indica exatamente o motivo — o documento não tem chip, o certificado do país emissor não está disponível, o dispositivo não possui leitor NFC, a verificação foi executada sem um SDK nativo (sem acesso a NFC a partir de um navegador), a chave de acesso ao chip não pôde ser obtida a partir da MRZ, um cartão My Number Card não pôde ser lido através de JPKI ou o utilizador optou por ignorar. Permanece `null` para resultados fora dessa taxonomia — mais frequentemente um utilizador que abandonou a meio da tentativa (status do relatório `Not Finished`) ou uma sessão onde o NFC ainda está pendente. Consulte [Motivos de omissão](https://docs.didit.me/pt/core-technology/nfc-verification/warnings-nfc-verification.md#motivos-para-ignorar) para conhecer os valores exatos. > [!NOTE] > > A documentação mais antiga referia um campo `nfc` singular. Esse formato **não** existe no endpoint de decisão v3 — apenas surge em destinos explicitamente configurados para webhooks V2, onde também inclui `chip_protocol` e `jpki`. Leia sempre `response.nfc_verifications[0]` e itere sobre o array. ## Esquema O esquema canónico campo a campo encontra-se na página de referência [Modelos de dados](https://docs.didit.me/pt/reference/data-models.md#verificação-nfc). Os campos abaixo refletem esse esquema canónico. | Campo | Tipo | Descrição | | - | - | - | | `status` | `"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"` | Estado do passo NFC (consulte os significados acima). | | `node_id` | string \| null | Nó do grafo do fluxo que produziu este relatório. Permite distinguir duas verificações NFC num fluxo de múltiplos passos. | | `is_nfc_skipped` | boolean | `true` quando este passo NFC foi explicitamente ignorado em vez de lido. | | `skip_reason` | string \| null | Motivo pelo qual o passo foi ignorado — definido apenas quando `is_nfc_skipped` é `true`. Mesmos valores que o `nfc_skip_reason` ao nível da sessão; consulte [Motivos de omissão](https://docs.didit.me/pt/core-technology/nfc-verification/warnings-nfc-verification.md#motivos-para-ignorar). | | `chip_protocol` | `"icao"` \| `"jpki"` | Como o chip é lido. `icao`: um chip de passaporte eletrónico ou eID ICAO 9303. `jpki`: um Japan My Number Card, cujo resultado se encontra sob `jpki`; os campos ICAO abaixo (`portrait_image`, `signature_image`, `chip_data`, `authenticity`, `certificate_summary`) ficam então `null`. Também definido em passos ignorados. | | `jpki` | object \| null | O que a leitura do My Number Card comprovou; consulte [Campos JPKI](#campos-jpki). `null` para chips ICAO, para passos ignorados e quando o passo foi encerrado sem qualquer leitura de cartão. | | `portrait_image` | string (URL assinada) \| null | Retrato extraído do chip (DG2). Ligação pré-assinada de curta duração — descarregue de imediato; volte a obter a decisão para um novo URL. | | `signature_image` | string (URL assinada) \| null | Imagem da assinatura do titular a partir do chip (DG7), quando presente. O mesmo comportamento de URL pré-assinada 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 de grupos de dados lidos), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (código de documento MRZ, p. ex., `P`), `document_number`, `optional_data`, os dígitos de controlo 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, `place_of_birth` e `address` são adicionados (e `full_name` / `full_name_non_latin` para documentos com um nome não latino); caso contrário, estas chaves estão **ausentes**, e não null. `null` quando o passo NFC foi ignorado. | | `authenticity` | object \| null | Resultados da autenticação passiva ICAO, abaixo. `null` para uma leitura JPKI. | | `authenticity.sod_integrity` | boolean | `true` quando a assinatura do SOD encadeia 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 grupo de dados 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` (marcas temporais como `YYYY-MM-DD HH:MM:SS`), mais um objeto `validation` com os resultados das verificações individuais (`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 o passo foi ignorado. | | `warnings[]` | array | Avisos ao nível do módulo, cada um com `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description` e `node_id` — consulte [Avisos de NFC](https://docs.didit.me/pt/core-technology/nfc-verification/warnings-nfc-verification.md). | ## Valores de estado | Estado | Significado | Efeito a jusante | | - | - | - | | `Approved` | Chip lido e nenhum aviso acionado com uma ação de Review ou Decline — incluindo o caso em que foram acionados avisos, mas a respetiva ação configurada é "No action". | Conta como uma verificação NFC bem-sucedida; não coloca, por si só, a sessão em análise. | | `In Review` | Foi acionado um aviso cuja ação configurada é Review (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME`, ou um dos avisos `JPKI_*`, dependendo das suas definições). | A sessão também transita para `In Review` até que um revisor intervenha. | | `Declined` | Foi acionado um aviso cuja ação configurada é Decline. | A sessão é recusada, a menos que outra ramificação aprovada satisfaça o fluxo. | | `Not Finished` | O utilizador abandonou o passo NFC, o dispositivo não tinha suporte NFC ou a leitura do chip nunca foi concluída. | A ramificação NFC não produziu um resultado; verifique as alternativas de contingência do fluxo. | | `Resub Requested` | Um revisor solicitou o reenvio deste passo. | Uma nova tentativa substitui este relatório assim que o utilizador 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` de NFC por si sós. Consulte [Avisos de NFC](https://docs.didit.me/pt/core-technology/nfc-verification/warnings-nfc-verification.md) para obter a matriz de comportamento completa. ## Exemplos ### Aprovada — leitura do chip efetuada e criptograficamente válida ```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 através de JPKI ainda não está ativada em produção. Até lá, um Cartão My Number ignora o passo de NFC com o motivo de omissão `JPKI_UNAVAILABLE`. ### Campos JPKI | Campo | Tipo | Descrição | | - | - | - | | `jpki.certificate_types` | array de `"user_authentication"` \| `"signature"` | Os certificados do cartão lidos. O certificado `user_authentication` (PIN de 4 dígitos) é sempre lido; `signature` (PIN de assinatura) é lido quando a definição `jpki_request_attributes` do nó de NFC está ativada, o que é a predefinição. | | `jpki.chain_valid` | boolean | `true` quando todos os certificados encadeiam na autoridade de certificação JPKI do seu tipo, estão dentro do respetivo período de validade e são certificados do Cartão My Number desse tipo. | | `jpki.signature_valid` | boolean | `true` quando todas as assinaturas efetuadas pelo cartão sobre o desafio de utilização única são verificadas. O cartão só assina após a introdução do PIN, o que comprova que a pessoa possui o cartão 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, por o cartão ter sido dado como perdido. `unchecked`: não foi disponibilizada nenhuma resposta de revogação, pelo que não é possível descartar que o cartão esteja revogado; nunca é tratado como `good`. A revogação só é verificada quando a cadeia e a assinatura são válidas. | | `jpki.ca_generation` | string \| null | Geração da autoridade de certificação JPKI que emitiu os certificados, por exemplo `"2023"`. `null` quando nenhum certificado forma uma cadeia até uma autoridade de certificação JPKI. | | `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`. O campo `failure` é `null` quando a cadeia é válida, caso contrário é um dos seguintes: `unreadable_certificate`, `untrusted_issuer`, `expired`, `not_yet_valid`, `wrong_policy` (não é um certificado do Cartão My Number desse tipo) ou `key_usage`. | | `jpki.attributes` | object \| null | Os dados do titular a partir do certificado de assinatura, assim que a sua cadeia seja válida: `full_name` (conforme registado, normalmente em sistema de escrita japonês), `date_of_birth` (`YYYY-MM-DD`), `gender` (`M`, `F` ou `null`), `address` e `name_substitute_characters` / `address_substitute_characters`, que assinalam carateres substituídos por um caratere substituto por estarem fora do conjunto de carateres padrão (`null` se nenhum tiver sido substituído). `null` quando o certificado de assinatura não foi solicitado ou a sua cadeia não é válida. | | `jpki.attributes_match_ocr` | boolean \| null | `true` quando os atributos correspondem aos dados lidos a partir da fotografia do mesmo cartão, `false` quando algum deles difere (`JPKI_AND_OCR_DATA_NOT_SAME`), `null` quando nada pôde ser comparado, incluindo sempre que `attributes` seja `null`. | | `jpki.mismatched_attributes` | array de string | Os atributos que diferem dos dados da fotografia (`full_name`, `date_of_birth`, `gender`, `address`), nunca os seus valores. | O relatório nunca contém os certificados em si, os respetivos números de série, as assinaturas ou o Número Individual de 12 dígitos do cartão (My Number), que o passo de 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": [] } ] } ``` Com a verificação de revogação indisponível para uma leitura, o mesmo relatório apresenta `revocation_status: "unchecked"`, um aviso `JPKI_REVOCATION_UNCHECKED` e `status: "In Review"` sob as definições predefinidas. Consulte [avisos de NFC](https://docs.didit.me/pt/core-technology/nfc-verification/warnings-nfc-verification.md#japan-my-number-card-jpki). ## Nota de segurança Os dados do chip NFC são assinados pela autoridade emissora, pelo que um relatório aprovado com `sod_integrity: true` e `dg_integrity: true` constitui a evidência de identidade mais robusta que a Didit pode produzir. Trate os URLs de imagem assinados (`portrait_image`, `signature_image`) como de curta duração: descarregue-os prontamente e não os guarde publicamente em cache — solicite novamente a decisão quando necessitar de ligações novas. ## Relacionado * [Avisos de NFC](https://docs.didit.me/pt/core-technology/nfc-verification/warnings-nfc-verification.md) — enumeração completa de avisos, causas e resolução. * [Webhooks](https://docs.didit.me/pt/integration/webhooks.md) — escute o evento `status.updated` para receber o relatório de NFC. * [Modelos de dados — Verificação NFC](https://docs.didit.me/pt/reference/data-models.md#verificação-nfc) — esquema canónico com todos os campos. * [Documentos suportados](https://docs.didit.me/pt/core-technology/nfc-verification/supported-documents-nfc-verification.md) — que documentos eletrónicos a Didit consegue ler através de NFC. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.