> ## 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.
# API de verificação NFC: passaporte eletrónico e eID
> A Didit valida passaportes eletrónicos e eIDs via chip NFC. Autenticação criptográfica inviolável de máxima segurança por $0.15 por chamada.
A autenticação baseada em NFC permite verificar documentos de identidade através da leitura do chip seguro integrado em passaportes e cartões de cidadão modernos, recorrendo às funcionalidades NFC de um telemóvel. Isto oferece o **nível de segurança mais elevado disponível** para a Verificação de identidade.
Prompt de integração da Verificação NFC
Copiar o prompt para a área de transferência
\
\````# Goal
Integrate Didit NFC Verification — cryptographic ePassport / eID chip read — into your app.
\# Delivery mode
NFC is **session-only**. There is no standalone /v3/nfc/ endpoint. The chip is read by the Didit Web/Mobile SDK during a hosted session, which uses the device's NFC radio.
\# Steps
1\. Create a workflow that includes the NFC feature (Business Console or POST /v3/workflows/). NFC normally runs alongside ID Verification: the user first photographs the document so the SDK derives BAC/PACE keys from the MRZ, then taps the chip.
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open the returned session.url on a mobile device with NFC (iOS 13+/Android with NFC enabled), or mount the native SDK in your app.
4\. After completion fetch the decision — GET /v3/session/{sessionId}/decision/ (or subscribe to session.status.updated).
curl (create session):
\```bash
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-123",
"callback": "https://yourapp.com/post-kyc"
}'
\```
\# Decision shape
The NFC result is returned under the plural array `nfc_verifications[]` on the decision payload.
\> Heads-up: the V3 schema deliberately keeps the **plural-array** name `nfc_verifications[]` even though early integrators occasionally hit a singular `nfc_verification` key. Always read from the plural array — it is the canonical, multi-instance shape and matches every other feature.
\# Status enum (per nfc_verifications[].status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"
\# Warnings (LogWarningChoices.NFC)
The warnings[] array on each nfc_verification includes risk codes such as:
NFC_NOT_READ, NFC_DATA_INVALID, NFC_DATA_DOES_NOT_MATCH_OCR, NFC_BAC_FAILED, NFC_PASSIVE_AUTHENTICATION_FAILED, NFC_ACTIVE_AUTHENTICATION_FAILED, NFC_CHIP_CLONED, NFC_DOCUMENT_REVOKED.
Full catalogue: /core-technology/nfc-verification/warnings-nfc-verification.
\# Failure modes to handle
\- Device has no NFC chip or NFC is disabled — the SDK falls back to OCR + face match; nfc_verifications[] will be empty.
\- The user fails to hold the chip long enough — status="Declined" with NFC_NOT_READ or NFC_BAC_FAILED. Allow a retry.
\- nfc_verifications[].status="Declined" with NFC_DATA_DOES_NOT_MATCH_OCR — the chip and the printed data disagree (likely tampered document). Do not approve.
\- Passive Authentication failed — the chip's signing certificate did not chain back to a trusted CSCA. Stop the flow.
\# Japan My Number Card (JPKI)
\- The My Number Card is read through JPKI, not ICAO 9303: native SDKs only, and the person enters the card PIN. Its item has chip_protocol "jpki", its evidence under jpki (chain_valid, signature_valid, revocation_status good | revoked | unchecked, attributes, attributes_match_ocr), and null ICAO fields (chip_data, authenticity, certificate_summary).
\- iOS host apps add D392F000260100000001 to com.apple.developer.nfc.readersession.iso7816.select-identifiers.
\- Not enabled in production yet: until it is, a My Number Card in a native SDK on an NFC phone skips NFC with nfc_skip_reason JPKI_UNAVAILABLE.
\# See also
\- Canonical schema: /reference/data-models#nfc-verification
\- Per-feature report: /core-technology/nfc-verification/report-nfc-verification
\- Risk catalogue: /core-technology/nfc-verification/warnings-nfc-verification
\- Supported documents: /core-technology/nfc-verification/supported-documents-nfc-verification
\- Full integration playbook: /integration/integration-prompt````
\
Colar em
***## Principais vantagens| Vantagem | Descrição |
| - | - |
| **Segurança máxima** | Verifica assinaturas criptográficas diretamente a partir das entidades emissoras governamentais |
| **Fácil de utilizar** | Funciona automaticamente com qualquer telemóvel equipado com NFC |
| **Inviolável** | Deteta a manipulação de documentos invisível ao olho humano |
| **Dados abrangentes** | Extrai dados adicionais não disponíveis apenas através de OCR |
| **Alternativa flexível** | Recorre de forma fluida à verificação padrão se o NFC não estiver disponível |***## Como ativar a Verificação NFC### Integração do SDK nativo (Recomendada)A verificação NFC está disponível através dos nossos **SDKs nativos**, que fornecem acesso total às funcionalidades NFC do dispositivo:| Plataforma | Suporte NFC | Documentação |
| - | - | - |
| **iOS** | ✅ Suporte total | [Documentação do SDK para iOS](https://docs.didit.me/pt/integration/native-sdks/ios-sdk.md) |
| **Android** | ✅ Suporte total | [Documentação do SDK para Android](https://docs.didit.me/pt/integration/native-sdks/android-sdk.md) |O SDK para iOS processa toda a configuração de NFC automaticamente, incluindo:- Identificadores de aplicação ISO7816 para passaportes eletrónicos (ePassports)
- Configuração de permissões e capacidades
- Leitura do chip em tempo real com feedback visual### Integração Web> ⚠️ **Limitações do navegador**
>
> A verificação NFC **não está disponível em navegadores web** devido a restrições de plataforma:
>
> | Navegador | Suporte NFC |
> | - | - |
> | **Chrome (Android)** | Web NFC API experimental - instável, requer permissões explícitas |
> | **Safari (iOS)** | Sem suporte para Web NFC API |
> | **Outros navegadores** | Sem suporte |
>
> Para integrações web, a verificação NFC é ignorada automaticamente e os utilizadores avançam com a verificação padrão de documento + selfie.***## Como funciona**1. Iniciação da sessão**O utilizador inicia o processo de verificação através da sua aplicação ou plataforma:- **SDK nativo**: Inicie o fluxo de verificação diretamente na sua aplicação
- **Web/Mobile Web**: O utilizador é orientado a usar a Didit App para verificação com NFC, ou continua com a verificação padrão**2. Captura de fotografia do documento**O utilizador fotografa o seu documento de identificação, capturando:- **MRZ** (Zona de leitura automática) — utilizada para derivar as chaves de acesso ao chip
- **Imagens da frente e do verso do documento** — dados visuais e elementos de segurança
- **Elementos visuais de segurança** — hologramas, marcas de água, microimpressão**3. Deteção de suporte a NFC**O sistema verifica automaticamente a compatibilidade do dispositivo e do documento:| Verificação | Descrição |
| - | - |
| **Tipo de documento** | É um passaporte eletrónico/eID com chip NFC? |
| **Capacidade do dispositivo** | O telemóvel suporta a leitura de NFC? |
| **Permissões** | As permissões necessárias de NFC foram concedidas? |> [!NOTE]
>
> Se o NFC não estiver disponível, a verificação continua sem interrupções com a verificação padrão de documento + biometria.**4. Leitura do chip NFC**Para dispositivos e documentos compatíveis:1) O utilizador é orientado a posicionar o seu documento junto ao leitor NFC do telemóvel
2) O feedback visual mostra o progresso da leitura em tempo real
3) É estabelecida uma comunicação segura com o chip utilizando os protocolos PACE/BAC**5. Extração de dados**O sistema extrai dados abrangentes do chip de acordo com as normas **ICAO 9303**:| Grupo de dados | Conteúdo | Descrição |
| - | - | - |
| **SOD** | Objeto de segurança do documento | Assinaturas digitais para todos os grupos de dados |
| **DG1** | Dados pessoais | Nome, número de identificação, data de nascimento, data de validade |
| **DG2** | Imagem facial | Fotografia digital de alta resolução do titular |
| **DG7** | Assinatura | Representação digital da assinatura do titular |
| **DG11-14** | Dados adicionais | Podem incluir impressões digitais, leituras de íris (se armazenadas) |**6. Verificação criptográfica**Os dados extraídos passam por uma verificação criptográfica rigorosa:> [accordion] Verificação da assinatura digital
>
> O hash de cada grupo de dados é verificado contra as assinaturas armazenadas no SOD, garantindo a integridade dos dados.> [accordion] Validação da cadeia de certificados
>
> A cadeia de confiança é validada: **Certificado do documento → CA de assinatura do país → ICAO PKD Root**, efetuando a validação contra as listas principais da CSCA e o Diretório de Chaves Públicas da ICAO.> [accordion] Verificação de revogação de certificados
>
> Os certificados são verificados contra Listas de Revogação de Certificados (CRLs) para assegurar que não foram revogados e que o documento não foi reportado como roubado/comprometido.> [accordion] Validação cruzada
>
> Os dados extraídos por NFC são validados de forma cruzada contra os dados de OCR das fotografias do documento, a comparação biométrica facial e a verificação do checksum da MRZ.**7. Resultado e pontuação de confiança**O resultado final da verificação inclui:| Resultado | Descrição |
| - | - |
| **Estado da verificação NFC** | Bem-sucedida, falhada ou ignorada |
| **Pontuação de consistência dos dados** | Nível de correspondência entre os dados NFC e os dados visuais |
| **Validação de certificados** | Estado da verificação de toda a cadeia |
| **Aumento de confiança** | O NFC aumenta significativamente a confiança na verificação global |***## Documentos suportadosA verificação NFC funciona com **passaportes eletrónicos** e **eIDs** que contenham um chip NFC, habitualmente indicado por este símbolo no documento:A maioria dos passaportes emitidos após 2006 contém chips NFC. A cobertura varia consoante o país no caso dos cartões de cidadão/identidade nacionais. Consulte todos os [documentos suportados](https://docs.didit.me/pt/core-technology/nfc-verification/supported-documents-nfc-verification.md).O Japan My Number Card tem um tipo diferente de chip, lido através de JPKI em vez do ICAO 9303. Consulte [Japan My Number Card (JPKI)](#cartão-my-number-do-japão-jpki).***## Cartão My Number do Japão (JPKI)O Cartão My Number do Japão (マイナンバーカード) tem um chip, mas não do padrão ICAO 9303. Contém certificados emitidos sob a JPKI, a infraestrutura de chave pública do Japão, e chaves privadas que apenas assinam após o titular introduzir o PIN do cartão. A Didit lê-o no mesmo passo de NFC, através da JPKI em vez da ICAO 9303, e cada resultado de NFC indica qual o protocolo utilizado em `chip_protocol` (`icao` ou `jpki`).> [!WARNING]
>
> **Ainda não disponível.** A leitura do My Number Card através da JPKI não está ativada em produção. Até estar disponível, um My Number Card capturado num SDK nativo ignora o passo de NFC com o motivo de omissão `JPKI_UNAVAILABLE`, e o cartão é verificado com captura de documento e correspondência facial como anteriormente.### Requisitos| Requisito | Detalhe |
| - | - |
| **Documento** | Apenas o Cartão My Number do Japão. Os passaportes japoneses mantêm a leitura de chip ICAO 9303. |
| **Integração** | Uma versão do SDK nativo que leia My Number Cards (iOS, Android ou os SDKs React Native e Flutter baseados nestes). O SDK informa a Didit de que pode ler JPKI; uma versão mais antiga ignora o passo com `JPKI_UNAVAILABLE`. As integrações Web e WebView ignoram-no com `INTEGRATION_WITHOUT_NFC_ACCESS`. |
| **Dispositivo** | Um telemóvel com leitor de NFC. Sem este, o passo é ignorado com `DEVICE_WITHOUT_NFC`. |
| **Aplicação anfitriã iOS** | `D392F000260100000001` nos identificadores de seleção ISO7816 da aplicação. Consulte a [configuração de NFC para iOS](https://docs.didit.me/pt/integration/native-sdks/ios-sdk.md#configuração-de-nfc). |
| **Pessoa** | Conhece o PIN de 4 dígitos do cartão e também a sua palavra-passe de assinatura quando o seu fluxo solicita os dados do titular. |### O que a pessoa faz**1. Fotografar o cartão**A pessoa captura o My Number Card no passo de verificação de identidade, tal como com qualquer documento. A Didit reconhece o cartão e envia um passo de NFC com JPKI em vez da leitura de chip de passaporte.**2. Introduzir o PIN do cartão**O SDK solicita o PIN de 4 dígitos do cartão (利用者証明用電子証明書の暗証番号). Quando a definição `jpki_request_attributes` do nó de NFC está ativada (o padrão), também solicita a palavra-passe de assinatura, também chamada de PIN de assinatura (署名用電子証明書の暗証番号, 6 a 16 letras maiúsculas e números).**3. Aproximar o cartão do telemóvel**O SDK lê os certificados do cartão e o cartão assina um desafio de utilização única da Didit com a sua própria chave. O SDK envia os certificados e as assinaturas. Os PINs vão apenas para o cartão, nunca para a Didit.> [!NOTE]
>
> O cartão contabiliza as tentativas incorretas: bloqueia o PIN de 4 dígitos após 3 tentativas consecutivas e a palavra-passe de assinatura após 5; um código bloqueado tem de ser reposto nos serviços municipais do titular. Após uma introdução incorreta, o SDK mostra quantas tentativas restam. Nunca efetua a última tentativa: quando resta apenas uma, para e informa a pessoa sobre onde a pode repor. Peça às pessoas para terem o seu PIN e a palavra-passe de assinatura prontos antes de começarem.### O que a Didit verifica| Verificação | O que a Didit verifica | Aviso em caso de falha (ação padrão) |
| - | - | - |
| **Cadeia de certificados** | Todos os certificados formam uma cadeia até à autoridade de certificação JPKI do respetivo tipo, estão dentro do seu período de validade e são certificados do My Number Card (`jpki.chain_valid`). | `JPKI_CERTIFICATE_INVALID` (Recusar) |
| **Cartão e PIN** | A assinatura do cartão sobre o desafio de utilização única é validada com o respetivo certificado (`jpki.signature_valid`). O cartão apenas assina após o seu PIN ser introduzido, o que prova que a pessoa detém o cartão e conhece o PIN. | `JPKI_SIGNATURE_INVALID` (Recusar) |
| **Revogação** | Nenhum certificado foi revogado (`jpki.revocation_status`). | `JPKI_CERTIFICATE_REVOKED` quando `revoked` (Recusar), `JPKI_REVOCATION_UNCHECKED` quando `unchecked` (Revisão) |
| **Dados do titular** | O nome, data de nascimento, sexo e morada no certificado de assinatura correspondem aos dados lidos a partir da fotografia do mesmo cartão (`jpki.attributes_match_ocr`, `jpki.mismatched_attributes`). | `JPKI_AND_OCR_DATA_NOT_SAME` (Revisão) |Cada ação é uma definição no nó de NFC, pelo que pode alterá-la para **Sem ação**, **Revisão** ou **Recusar**. Consulte os [avisos de NFC](https://docs.didit.me/pt/core-technology/nfc-verification/warnings-nfc-verification.md#japan-my-number-card-jpki) e a [configuração da funcionalidade de NFC](https://docs.didit.me/pt/management-api/workflows/feature-configs.md#nfc-/-passaporte-eletrónico).### O que significa um estado de revogação não verificado`revocation_status: "unchecked"` significa que a Didit verificou a cadeia de certificados e a assinatura do cartão, mas não obteve resposta sobre se um certificado foi revogado. Um certificado é revogado quando, por exemplo, o cartão é comunicado como perdido. Como não é possível excluir que o cartão esteja revogado, `unchecked` nunca é tratado como `good`. Aciona o aviso `JPKI_REVOCATION_UNCHECKED`, que envia o passo de NFC para revisão por padrão. Escolha um resultado diferente com `jpki_revocation_unchecked_action`.Quando a cadeia de certificados ou a assinatura não é válida, a Didit não consulta a revogação: o estado permanece `unchecked` e apenas o aviso da cadeia ou da assinatura é acionado.### Dados do titular e privacidade- Com `jpki_request_attributes` ativado, a decisão inclui o nome do titular, data de nascimento, sexo e morada a partir do certificado de assinatura sob `jpki.attributes`. Com esta opção desativada, a pessoa apenas introduz o PIN de 4 dígitos: a leitura continua a comprovar o cartão e o PIN, mas não transporta dados do titular e não é comparada com a fotografia do cartão.
- O passo de NFC nunca lê o Número Individual de 12 dígitos (My Number) do cartão a partir do chip.
- A decisão reporta o que o cartão comprovou, nunca os certificados em si, os seus números de série ou as assinaturas.O resultado completo é descrito no [relatório de verificação NFC](https://docs.didit.me/pt/core-technology/nfc-verification/report-nfc-verification.md#cartão-my-number-do-japão-jpki).***## Exemplos de integração### SDK para iOS (Já disponível)```swift theme={null}
import DiditSdk
// NFC is automatically enabled when the document supports it
let config = DiditSdk.Configuration(
// NFC configuration is handled automatically
// Just ensure your app has the required entitlements
)
let result = try await DiditSdk.shared.startVerification(
with: sessionId,
configuration: config
)
```**[Documentação completa do SDK para iOS →](https://docs.didit.me/pt/integration/native-sdks/ios-sdk.md)**### SDK para Android (Já disponível)```kotlin theme={null}
import me.didit.sdk.DiditSdk
// NFC is automatically enabled when the document supports it
DiditSdk.startVerification(
token = "your-session-token"
) { result ->
handleResult(result)
}
```**[Documentação do SDK para Android →](https://docs.didit.me/pt/integration/native-sdks/android-sdk.md)*****## Arquitetura de segurança```
┌─────────────────────────────────────────────────────────────┐
│ NFC Verification Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │ Document │───▶│ Phone │───▶│ Didit Backend │ │
│ │ NFC Chip │ │ NFC Read │ │ │ │
│ └──────────┘ └──────────┘ │ ┌────────────────┐ │ │
│ │ │ ICAO PKD │ │ │
│ │ │ Validation │ │ │
│ │ └────────────────┘ │ │
│ │ ┌────────────────┐ │ │
│ │ │ CSCA Master │ │ │
│ │ │ List Check │ │ │
│ │ └────────────────┘ │ │
│ │ ┌────────────────┐ │ │
│ │ │ CRL Revocation │ │ │
│ │ │ Check │ │ │
│ │ └────────────────┘ │ │
│ └──────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Verification Result │ │
│ │ + Confidence Score │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```***## FAQ
**E se o telemóvel do utilizador não suportar NFC?**
O fluxo de verificação deteta automaticamente a capacidade NFC. Se não estiver disponível, os utilizadores prosseguem com a verificação padrão de documento + selfie. A verificação continua a ser segura, apenas sem o reforço adicional de confiança do NFC.
**E se o documento não tiver um chip NFC?**
Muitos documentos (especialmente passaportes mais antigos e alguns documentos de identificação nacionais) não têm chips NFC. O sistema deteta esta situação e continua sem problemas com a verificação padrão.
**Quanto é que a verificação NFC melhora a precisão?**
A verificação NFC fornece prova criptográfica da autenticidade do documento diretamente do governo emissor. Isto aumenta significativamente a confiança no resultado da verificação e deteta falsificações sofisticadas que poderiam passar numa inspeção visual.
**A verificação NFC é obrigatória?**
Não. O NFC é uma melhoria, não um requisito. O seu fluxo de verificação pode ser configurado para exigir NFC, dar preferência ao NFC quando estiver disponível ou ignorá-lo por completo com base na sua tolerância ao risco.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.