Verificação NFC: relatório de chip e autenticidade

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). 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.
Webhooks — os payloads de status.updated incluem o mesmo array nfc_verifications[] assim que o passo de NFC produzir dados. Consulte Webhooks.
NFC autónomo — para submissão direta do chip, consulte a visão geral de NFC.

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 para conhecer os valores exatos.

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

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.

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 para obter a matriz de comportamento completa.

Exemplos

Aprovada — leitura do chip efetuada e criptograficamente válida

{
  "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": []
    }
  ]
}

Recusada — discrepâ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)

Um Cartão My Number do Japão é lido através de JPKI em SDKs nativos: a pessoa introduz o PIN do cartão e o cartão assina um desafio de utilização única (consulte como funciona). O seu relatório tem chip_protocol: "jpki" e apresenta 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 da ICAO.

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

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

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 — enumeração completa de avisos, causas e resolução.
Webhooks — escute o evento status.updated para receber o relatório de NFC.
Modelos de dados — Verificação NFC — esquema canónico com todos os campos.
Documentos suportados — que documentos eletrónicos a Didit consegue ler através de NFC.

Autenticação

Verificação

Monitorização

Plataforma

Verificação NFC: relatório de chip e autenticidade

Visão geral

Onde surge nas respostas da API

Esquema

Valores de estado

Exemplos

Aprovada — leitura do chip efetuada e criptograficamente válida

Recusada — discrepâ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

Relacionado

​Visão geral

​Onde surge nas respostas da API

​Esquema

​Valores de estado

​Exemplos

​Aprovada — leitura do chip efetuada e criptograficamente válida

​Recusada — discrepâ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

​Relacionado

Visão geral

Onde surge nas respostas da API

Esquema

Valores de estado

Exemplos

Aprovada — leitura do chip efetuada e criptograficamente válida

Recusada — discrepâ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

Relacionado