Skip to content
Guida del Centro assistenza · NFC e contactless
3 min di letturaVerificato 2026-11-16

Apple VAS

Requisiti Apple Value Added Services (VAS): certificato VAS, autorizzazione commerciale e lettori abilitati.

In questa guida

Che cos'è Apple Value Added Services (VAS)?

Apple Value Added Services (VAS) è il protocollo di comunicazione contactless NFC di Apple basato su ISO/IEC 14443 Tipo A/B (13,56 MHz). Consente a un payload cifrato del pass (nfc.message, fino a 64 byte) archiviato in Apple Wallet su iPhone o Apple Watch di essere trasmesso in modalità wireless quando avvicinato a un lettore contactless certificato Apple — senza dover sbloccare lo schermo per mostrare un codice a barre e senza addebitare accidentalmente una carta di credito o debito Apple Pay.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
ENTITLEMENT APPLE VAS E HANDSHAKE ECDH P-256
FASE 01 FASE 1: ENTITLEMENT E PROVISIONING CHIAVI (NFC entitlement request)
1
Il merchant richiede Apple NFC Entitlement (status: PENDING -> APPROVED)
2
Genera coppia di chiavi ECDH P-256 (prime256v1)
Chiave pubblica (encryptionPublicKey)Nel dizionario nfc pass.json
Chiave privataCaricata nel Secure Element lettore NFC (Slot 1..6)
3
Transizione NFC entitlement requeststatus: PROVISIONED
FASE 02 FASE 2: POLLING CONTACTLESS ISO/IEC 14443 E DECIFRATURA
1
Il lettore invia SELECT OSE + SHA-256(pass.com.yourbrand.loyalty)
2
iPhone / Apple Watch risveglia Wallet e verifica requiresAuthentication
3
Il dispositivo genera chiave effimera ECDH P-256, cifra 64 byte nfc.message con segreto condiviso (ANSI X9.63 KDF + AES-256-GCM)
4
Il lettore decifra con la chiave privata salvataEstrae serialNumber
5
Il lettore chiama POST/api/v1/reader/redeem o POST/api/v1/reader/validate

Prerequisiti obbligatori (conformità rigorosa)

Importante: Apple VAS non viene attivato automaticamente creando un workspace Passinstance o configurando un link NDEF. Poiché Apple limita la trasmissione NFC via Secure Element / PassKit a livello di kernel iOS, ogni distribuzione Apple VAS in produzione richiede tre componenti obbligatori:

  1. 1
    Approvazione Apple NFC / Enhanced PassKit Entitlement: L'organizzazione deve richiedere e ottenere da Apple l'NFC-Enabled Pass Entitlement sul proprio account Apple Developer (developer.apple.com/contact/passkit/). I certificati Apple Pass Type ID standard privi del flag NFC entitlement portano iOS a ignorare il dizionario nfc dentro pass.json.
  2. 2
    Flusso richiesta certificato NFC Passinstance (NFC entitlement request): Invii e tracci la richiesta di attivazione NFC (POST /api/v1/certificates/nfc-requests) e abbini i dispositivi lettore (NFC Settings API) in modo che la propria chiave pubblica di cifratura si leghi correttamente al dizionario nfc dei file .pkpass.
  3. 3
    Hardware lettore certificato Apple VAS: I terminali da banco o tornello devono implementare il protocollo Apple VAS (come Certified Apple VAS & Google Smart Tap NFC readers, Verifone o terminali Ingenico abilitati VAS) configurati con l'hash SHA-256 del proprio passTypeIdentifier e con la corrispondente chiave privata di decifratura ECDH P-256.

Ciclo di vita e stati di NFC entitlement request (NfcCertificateRequestStatus)

Passinstance traccia la richiesta di abilitazione Apple VAS del workspace tramite il modello NFC entitlement request (NfcCertificateRequestStatus):

Stato (NfcCertificateRequestStatus)Significato operativo
PENDINGIl workspace ha inviato una richiesta Apple NFC/VAS; in attesa di esame e approvazione dell'entitlement.
APPROVEDRichiesta di entitlement approvata; pronto per emettere/caricare il certificato Apple TYPE_NFC abilitato NFC.
REJECTEDRichiesta respinta oppure verifica Apple Team / Pass Type ID inviata incompleta.
PROVISIONEDCertificato Pass Type abilitato NFC (CertificateType.TYPE_NFC) e chiavi di cifratura attivi in Passinstance.

Endpoint API per Apple VAS e richieste NFC (NFC Request API)

MetodoPercorso endpointPermesso richiestoDescrizione
POST/api/v1/certificates/nfc-requestscertificates:manageCrea una nuova NFC entitlement request (status: PENDING) tramite request payload.
GET/api/v1/certificates/nfc-requestscertificates:readElenca tutti i record NFC entitlement request per il workspace.
GET/api/v1/certificates/nfc-requests/:idcertificates:readRecupera dettagli e stato di revisione corrente per una specifica richiesta certificato NFC.
POST/api/v1/certificates/nfc-requests/:id/reviewAdmin piattaformaEsamina/fa transitare lo stato della richiesta (APPROVED, REJECTED, PROVISIONED) tramite request payload.
POST/api/v1/nfc/testAutenticatoEsegue un test di payload/configurazione NFC per un modello.

Esempio: creazione di una 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"
}

Risposta (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"
}

Serve supporto per dimensionare Apple VAS su un rollout multi-negozio o di controllo accessi? Contatti l'assistenza oppure consulti Configurazione pass NFC e Lettori NFC compatibili.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.