Skip to content
Guia da Central de Ajuda · NFC e sem contacto
3 min de leituraVerificado 2026-11-16

Apple VAS

Pré-requisitos do Apple Value Added Services (VAS): autorização de certificado VAS, pedido comercial e leitores.

Neste guia

O Que É o Apple Value Added Services (VAS)?

O Apple Value Added Services (VAS) é o protocolo de comunicação NFC sem contacto da Apple baseado na norma ISO/IEC 14443 Tipo A/B (13,56 MHz). Permite que um payload de passe encriptado (nfc.message, até 64 bytes) armazenado na Apple Wallet de um iPhone ou Apple Watch seja transmitido sem fios ao aproximá-lo de um leitor sem contacto certificado pela Apple — sem despertar o ecrã para mostrar um código de barras e sem cobrar acidentalmente um cartão de crédito ou débito Apple Pay.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
FLUXO DA ARQUITETURA DO SISTEMA: AUTORIZAÇÃO APPLE VAS E HANDSHAKE ECDH P-256
ETAPA 01 FASE 1: AUTORIZAÇÃO E APROVISIONAMENTO DE CHAVES (NFC entitlement request)
1
Comerciante pede Autorização NFC Apple (status: PENDING -> APPROVED)
2
Gerar Par de Chaves ECDH P-256 (prime256v1)
Chave Pública (encryptionPublicKey)No dicionário nfc de pass.json
Chave PrivadaAprovisionada no Secure Element do Leitor (Slot 1..6)
3
Transição NFC entitlement requeststatus: PROVISIONED
ETAPA 02 FASE 2: INTERROGAÇÃO SEM CONTACTO ISO/IEC 14443 E DESENCRIPTAÇÃO
1
O leitor difunde SELECT OSE + SHA-256(pass.com.yourbrand.loyalty)
2
iPhone / Apple Watch ativa a Carteira e valida requiresAuthentication
3
O dispositivo gera chave efémera ECDH P-256 e encripta nfc.message (64 bytes) com segredo partilhado (ANSI X9.63 KDF + AES-256-GCM)
4
O leitor desencripta o payload com a Chave PrivadaExtrai serialNumber
5
Leitor chama POST/api/v1/reader/redeem ou POST/api/v1/reader/validate

Pré-requisitos Obrigatórios (Conformidade Estrita)

Importante: O Apple VAS não é ativado automaticamente ao criar um espaço de trabalho na Passinstance ou ao ativar uma ligação NDEF. Como a Apple restringe a transmissão NFC do Secure Element / PassKit ao nível do kernel do iOS, todas as implementações Apple VAS em produção exigem três componentes obrigatórios:

  1. 1
    Aprovação da Autorização Apple NFC / Enhanced PassKit: A sua organização tem de solicitar e receber da Apple a autorização NFC-Enabled Pass Entitlement na sua conta Apple Developer (developer.apple.com/contact/passkit/). Os certificados Apple Pass Type ID padrão sem o sinalizador de autorização NFC fazem com que o iOS ignore o dicionário nfc dentro de pass.json.
  2. 2
    Fluxo de Pedido de Certificado NFC da Passinstance (NFC entitlement request): Submeta e acompanhe a sua ativação NFC (POST /api/v1/certificates/nfc-requests) e emparelhe dispositivos leitores (NFC Settings API) para que a sua chave pública de encriptação fique associada corretamente ao dicionário nfc do seu .pkpass.
  3. 3
    Hardware Leitor Certificado Apple VAS: Os terminais de balcão ou torniquetes têm de implementar o protocolo Apple VAS (como terminais Certified Apple VAS & Google Smart Tap NFC readers, Verifone ou Ingenico compatíveis com VAS) configurados com o hash SHA-256 do seu passTypeIdentifier e a chave privada de desencriptação ECDH P-256 correspondente.

Ciclo de Vida e Estados de NFC entitlement request (NfcCertificateRequestStatus)

A Passinstance acompanha o pedido de autorização Apple VAS do seu espaço de trabalho através do modelo NFC entitlement request (NfcCertificateRequestStatus):

Estado (NfcCertificateRequestStatus)Significado Operacional
PENDINGO espaço de trabalho submeteu um pedido Apple NFC/VAS; aguarda análise e aprovação da autorização.
APPROVEDPedido de autorização aprovado; pronto para emitir/carregar o certificado Apple TYPE_NFC habilitado para NFC.
REJECTEDPedido recusado ou a verificação submetida da Apple Team / Pass Type ID estava incompleta.
PROVISIONEDO Certificado Pass Type habilitado para NFC (CertificateType.TYPE_NFC) e as chaves de encriptação estão ativos na Passinstance.

Endpoints da API Apple VAS e Pedidos NFC (NFC Request API)

MétodoCaminho do EndpointPermissão NecessáriaDescrição
POST/api/v1/certificates/nfc-requestscertificates:manageCria um novo NFC entitlement request (status: PENDING) utilizando request payload.
GET/api/v1/certificates/nfc-requestscertificates:readLista todos os registos NFC entitlement request do seu espaço de trabalho.
GET/api/v1/certificates/nfc-requests/:idcertificates:readObtém os detalhes e o estado atual de revisão de um pedido de certificado NFC específico.
POST/api/v1/certificates/nfc-requests/:id/reviewAdministrador da PlataformaAnalisa/transita o estado do pedido (APPROVED, REJECTED, PROVISIONED) através de request payload.
POST/api/v1/nfc/testAutenticadoExecuta um teste de payload/configuração de passe NFC para um modelo.

Exemplo: Criar um NFC entitlement request (request payload)

JSON
POST /api/v1/certificates/nfc-requests
{
  "organizationName": "Phenix Roasters GmbH",
  "appleTeamId": "9A8B7C6D5E",
  "passTypeId": "pass.com.phenixroasters.loyalty",
  "websiteUrl": "https://phenixroasters.com",
  "useCaseDescription": "In-store loyalty tap redemption on NFC Terminal readers across 45 cafes",
  "contactEmail": "nfc-admin@phenixroasters.com"
}

Resposta (201 Created):

JSON
{
  "id": "nfcreq_01J9Z8A2B4C6D8E0F2G4H6J8",
  "organizationName": "Phenix Roasters GmbH",
  "appleTeamId": "9A8B7C6D5E",
  "passTypeId": "pass.com.phenixroasters.loyalty",
  "status": "PENDING",
  "createdAt": "2026-11-15T12:00:00.000Z"
}

Precisa de assistência para planear o Apple VAS numa implementação multilojas ou de controlo de acessos? Contacte o Suporte ou consulte Configuração de Passes NFC 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.