Skip to content
Guida del Centro assistenza · Certificati e credenzialiFase di onboarding 3
3 min di letturaVerificato 2026-11-16

Certificati Apple Wallet

Crea un Pass Type ID su Apple Developer, genera il CSR in Passinstance, carica .cer/.p12 e collegalo.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito
Elementi chiave dell'interfaccia

Template Settings — Firma e ID esterni (Ingrandito)

Controlla stato certificato di firma, ordinamento Wallet, stato Published e regole di unicità External ID.

Panoramica: perché sono necessari i certificati Apple Pass Type ID

Apple impone che ogni archivio .pkpass di produzione sia firmato crittograficamente mediante un Certificato Pass Type ID emesso sotto l'account Apple Developer Program dell'organizzazione (Certificate Management API su /api/v1/certificates). Il certificato svolge due funzioni critiche:

  1. 1
    Firma detached PKCS#7 del bundle: Firma manifest.json all'interno di ogni archivio .pkpass (collegandosi al certificato intermedio Apple WWDR G4/G6) in modo che iOS verifichi l'autenticità e mostri il nome verificato dell'organizzazione.
  2. 2
    Autenticazione push HTTP/2 APNs: Autentica le connessioni TLS HTTP/2 verso api.push.apple.com sotto il topic pass.com.<domain>.<name> del certificato, consentendo a Passinstance di risvegliare gli iPhone dei clienti per aggiornamenti live dei pass.
FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
PROVISIONING CERTIFICATO APPLE PASS TYPE
FASE 01 FASE 1: Genera chiave privata e CSR in Passinstance (Certificate Management API)
POST/api/v1/certificates/generate-csr
Genera chiave RSA a 2048 bit CertificatePkey (cifrata nel encrypted storage)
Restituisce .certSigningRequest (CSR) codificato in PEM
FASE 02 FASE 2: Apple Developer Portal (developer.apple.com)
1
Registra IdentifierPass Type ID (pass.com.yourbrand.loyalty)
2
Crea certificatoCarica CSR PassinstanceScarica pass.cer
FASE 03 FASE 3: Carica .cer firmato in Passinstance (POST/api/v1/certificates)
1
Analizza .cer X.509: estrae passTypeIdentifier, teamIdentifier, scadenza
2
Verifica il modulo della chiave pubblica rispetto a CertificatePkey salvata
3
Valida la catena di attendibilità verso Apple WWDR G4 / G6
4
Impacchetta PKCS#12 (.p12) cifrato nel encrypted storageStato: VALID / ACTIVE

Prerequisiti: È necessario un abbonamento attivo ad Apple Developer Program (ruolo Account Holder o Admin) per registrare Pass Type ID ed emettere certificati Pass Type ID di produzione. Sebbene Passinstance fornisca un certificato sandbox gestito per le demo iniziali dell'onboarding, è indispensabile associare il proprio certificato Pass Type ID prima di distribuire pass di produzione ai clienti — Apple non consente di migrare pass già installati a un diverso passTypeIdentifier o teamIdentifier dopo l'installazione.

Procedura passo per passo di configurazione del certificato

  1. 1
    Generazione del CSR in Passinstance: Acceda a Impostazioni -> Wallet -> Certificati Apple (/settings/workspace/wallet) e clicchi su Genera CSR (richiama POST /api/v1/certificates/generate-csr con passTypeId opzionale). Scarichi il file .certSigningRequest. Passinstance archivia la chiave privata RSA generata (CertificatePkey) in uno storage cifrato.
  2. 2
    Registrazione di un Pass Type ID in Apple Developer: Acceda a Apple Developer Portal -> Certificates, Identifiers & Profiles -> Identifiers, clicchi su +, selezioni Pass Type IDs e registri un identificativo in formato DNS inverso come pass.com.yourbrand.loyalty.
  3. 3
    Emissione del file .cer firmato in Apple Developer: Apra il nuovo Pass Type ID, clicchi su Create Certificate, carichi il file .certSigningRequest scaricato da Passinstance e scarichi il file pass.cer risultante.
  4. 4
    Caricamento di pass.cer in Passinstance: Carichi pass.cer tramite POST /api/v1/certificates (multipart/form-data, parametri opzionali teamIdentifier, passTypeId, demo, isNfcCertificate) oppure POST /api/v1/certificates/upsert (file + type: "TYPE_PASS" | "TYPE_NFC"). Passinstance collega il file .cer alla chiave privata generata, verifica la catena intermedia Apple WWDR G4/G6 e prepara il bundle di firma cifrato .p12.
  5. 5
    Associazione del certificato al modello: Apra le Impostazioni del modello e associ il proprio certificato Pass Type ID verificato.

Riferimento API per la gestione certificati (Certificate Management API)

MetodoPercorso endpointPermesso richiestoDescrizione
POST/api/v1/certificates/generate-csrcertificates:manageGenera una coppia di chiavi RSA (CertificatePkey) e restituisce una Certificate Signing Request PEM (.csr).
POST/api/v1/certificatescertificates:manageCarica un file .cer firmato da Apple tramite multipart/form-data, verifica la catena WWDR G4/G6 e attiva il certificato (CertificateType: `TYPE_PASS \TYPE_NFC`).
POST/api/v1/certificates/upsertcertificates:manageCrea o aggiorna/rinnova un certificato esistente da un .cer firmato (multipart/form-data, opzionali pkeyId, type, intermediatePem).
GET/api/v1/certificatescertificates:readElenca i certificati del workspace con passTypeIdentifier, teamIdentifier, validFrom, validTo e stato.
GET/api/v1/certificates/:idcertificates:readRestituisce i metadati X.509 e i dettagli per uno specifico ID certificato.
DELETE/api/v1/certificates/:idcertificates:manageRimuove un certificato non utilizzato o scaduto.

Esempio: generare un CSR e caricare pass.cer

1. Genera CSR (POST /api/v1/certificates/generate-csr):

JSON
POST /api/v1/certificates/generate-csr
{
  "passTypeId": "pass.com.phenixroasters.loyalty"
}

Risposta (200 OK):

JSON
{
  "success": true,
  "data": {
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCREUx...\n-----END CERTIFICATE REQUEST-----"
  },
  "description": "CSR generated successfully",
  "errors": [],
  "statusCode": 200
}

2. Carica .cer firmato (POST /api/v1/certificates):

Invii come multipart/form-data con campo file (pass.cer), oltre ai campi opzionali passTypeId, teamIdentifier e isNfcCertificate ("false" o "true"):

BASH
curl -X POST https://api.passinstance.com/api/v1/certificates \
  -H "X-API-Key: <API_KEY>" \
  -F "file=@./pass.cer" \
  -F "passTypeId=pass.com.phenixroasters.loyalty" \
  -F "isNfcCertificate=false"

Risposta (201 Created):

JSON
{
  "id": "cert_8841a9b0-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "passTypeIdentifier": "pass.com.phenixroasters.loyalty",
  "teamIdentifier": "9A8B7C6D5E",
  "type": "TYPE_PASS",
  "validFrom": "2026-11-15T10:18:00.000Z",
  "validTo": "2027-12-15T10:17:59.000Z"
}

Consulti Rinnovo e gestione dei certificati e Apple Wallet per la manutenzione del ciclo di vita.

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.