Skip to content
Guia da Central de Ajuda · NFC e sem contactoFase de integração 2
3 min de leituraVerificado 2026-11-16

Configuração de passes NFC

Distinga etiquetas NDEF abertas (abrem link de download) do resgate encriptado por leitor sem contacto.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface
Elementos-chave da interface

Configuração de código de barras, QR code e NFC (Zoom)

Configure o formato QR-Code, a origem do valor, o token dinâmico ({memberQrToken}), o texto alternativo ({passReference}) e o NFC.

Dois Usos Muito Diferentes de "NFC" em Passes de Carteira

Importante: Antes de definir o âmbito de pagamentos sem contacto ou controlo de acessos com as partes interessadas, distinga a Distribuição por Etiquetas NFC NDEF (etiquetas URL de norma aberta que funcionam com qualquer smartphone de imediato) do Resgate por Aproximação Encriptado (Apple VAS e Google Smart Tap, que transmitem um payload de passe encriptado da carteira para um terminal leitor NFC especializado).

CapacidadeFinalidadeProtocolo e ModeloHardware e Aprovação Necessários
Distribuição por Etiqueta NFC NDEFO cliente aproxima o telemóvel desbloqueado ao autocolante do balcão -> abre o URL Adicionar à Carteira ou PassFlowRegisto URI NDEF ISO/IEC 14443Apenas autocolante económico NTAG213/215; não requer hardware leitor nem Apple VAS.
Resgate por Aproximação (Apple VAS / Google Smart Tap)O cliente aproxima o telemóvel/Watch do terminal -> o leitor desencripta o payload do passe (message)Apple VAS e Google Smart Tap (modelo NFC e Template.nfc)Requer hardware leitor NFC VAS/Smart Tap + configuração de chave pública/privada do comerciante (não ativado por predefinição em todas as contas).

Modelo NFC do Passe e Arquitetura do Dicionário nfc no pass.json

Quando o resgate sem contacto está ativado num modelo (Template.nfc / modelo Passinstance database NFC), a Passinstance incorpora metadados criptográficos sem contacto tanto no dicionário nfc do pass.json da Apple Wallet como em smartTapRedemptionValue do objeto da Google Wallet:

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
FLUXO DA ARQUITETURA DO SISTEMA: PAYLOAD NFC ENCRIPTADO E HANDSHAKE DO TERMINAL
ETAPA 01 ESQUEMA NFC DE MODELO E PASSE (Modelo NFC)
nfcEnabled: true
message: Payload dinâmico (até 64 bytes, ex. serialNumber ou token)
encryptionPublicKey: Chave Pública ECDH P-256 em Base64 (prime256v1)
requiresAuthentication (nfcFaceIdRequired): Exigir Face ID / Touch ID
nfcNoBarcode: Ocultação opcional do código 2D visual na frente do cartão
pass.json Apple Wallet
ETAPA 02A "nfc": {
"message": "PI-8849-2026-X9", "encryptionPublicKey": "MDkwEw...", "requiresAuthentication": true }
[ Campo RF 13,56 M
TERMINAL LEITOR POS / ACESSOS
1
Difunde o Hash do Pass Type ID Apple
2
Executa Acordo de Chaves Efemérico EC
3
Reencaminha message desencriptado pPOST/api/v1/reader/redeem
WalletObject Google Wallet
ETAPA 02B "smartTapRedemptionValue": "<msg>"
"hasUsers": true
Associado a redemptionIssuers da Classe (collectorId/ECDH P-256)
ISO/IEC 14443 ]
C / Verifone / Ingenico) e Collector ID Google Smart Tap
P-256 e Desencriptação AES-GCMPOST/api/v1/scans ou

Propriedades e Restrições de Configuração NFC

Propriedade (NFC / Template.nfc)Chave pass.json AppleTipo e RestriçãoComportamento Técnico
messagenfc.messagestring (Máx. 64 bytes UTF-8)O payload em texto limpo encriptado pelo dispositivo e transmitido ao leitor NFC (assume por predefinição serialNumber ou externalId do passe).
encryptionPublicKeynfc.encryptionPublicKeystring (Base64 DER/PEM)Chave pública ECDH P-256 (prime256v1) comprimida ou não comprimida correspondente à chave privada carregada nos seus terminais leitores NFC.
nfcFaceIdRequirednfc.requiresAuthenticationbooleanQuando true, o iOS exige que o titular do passe se autentique via Face ID, Touch ID ou Código antes de transmitir o payload VAS.
nfcNoBarcodeOmite barcodes[]booleanQuando true, suprime o código de barras visual 2D QR/Aztec na frente do passe para que o passe só possa ser apresentado por aproximação NFC encriptada.

Exemplo: Dicionário nfc do pass.json da Apple Wallet e Configuração do Modelo

Quando nfcEnabled: true está configurado num modelo, a Passinstance serializa o dicionário nfc na raiz do pass.json:

JSON
{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.phenixroasters.access",
  "serialNumber": "PI-8849-2026-X9",
  "nfc": {
    "message": "PI-8849-2026-X9",
    "encryptionPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8v3x9K2m5N7p1Q4r6S8t0V2w4Y6z8A1b3C5d7E9f0G2h4J6k8L0m2N4p6Q8r0S==",
    "requiresAuthentication": true
  }
}

Para atualizar as definições NFC de um modelo através da API REST, aplique um patch ao recurso do modelo (e valide a configuração com POST /api/v1/nfc/test):

JSON
PATCH /api/v1/templates/7b9e4c12-3f81-4a90-b8d2-19c48a70e112
{
  "nfc": {
    "message": "{serialNumber}",
    "encryptionPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8v3x9K2m5N7p1Q4r6S8t0V2w4Y6z8A1b3C5d7E9f0G2h4J6k8L0m2N4p6Q8r0S==",
    "requiresAuthentication": true
  },
  "nfcFaceIdRequired": true,
  "nfcNoBarcode": false
}

Boa Prática: Mantenha o Código de Barras 2D Ótico de Contingência Ativo

A menos que esteja a implementar cartões de acesso de funcionários de alta segurança em que capturas de ecrã do código de barras tenham de ser estritamente impedidas (nfcNoBarcode: true ou addSecurityAnimation: true), mantenha nfcNoBarcode: false para que os passes apresentem um código de barras 2D QR ou Aztec de reserva. Isto garante que a equipa possa continuar a validar passes com câmaras óticas caso um terminal esteja offline ou a antena NFC do telemóvel de um cliente esteja desativada.

Consulte Âmbito dos Passes de Carteira NFC, Apple VAS, Google Smart Tap e Leitores NFC Compatíveis.

Documentação de produto e API relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.