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

Rinnovo e gestione certificati

Monitora la scadenza annuale e rinnova con lo stesso Pass Type ID evitando nuove installazioni agli utenti.

In questa guida

Panoramica: perché il monitoraggio della scadenza dei certificati è essenziale

I certificati Apple Pass Type ID (pass.com.yourbrand.*) hanno un periodo di validità rigoroso di 397 giorni (~13 mesi) imposto dalla Certification Authority di Apple. Se un certificato scade senza essere rinnovato:

  • I nuovi download non riescono: Passinstance non può generare firme PKCS#7 detached valide per i nuovi download .pkpass associati a quel certificato.
  • Gli aggiornamenti push APNs si interrompono: Il gateway HTTP/2 APNs di Apple (api.push.apple.com) rifiuta immediatamente le connessioni TLS autenticate con un certificato scaduto, bloccando gli aggiornamenti live di saldo e campi sugli iPhone già installati.
FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
RINNOVO CERTIFICATI A ZERO DOWNTIME
FASE 01 CRON DI MONITORAGGIO SCADENZE AUTOMATICO (Certificate Renewal Monitor)
Job giornaliero alle 02:00 controlla i certificati con validTo <= now + 30 gg
Avvisa i contatti del workspace di caricare il certificato rinnovato in tempo
FASE 02 FASE 1: GENERA CSR PER IL PASS TYPE ID ESISTENTE
POST/api/v1/certificates/generate-csr
Conserva l'esatto passTypeIdentifier (pass.com.yourbrand.loyalty)
Conserva il teamIdentifier Apple a 10 caratteri
FASE 03 FASE 2: ROTAZIONE CERTIFICATO SU APPLE DEVELOPER PORTAL
Apri il Pass Type ID esistenteCreate CertificateCarica CSR di rinnovo
Scarica pass.cer rinnovato (NON revocare il vecchio finché il nuovo è attivo)
FASE 04 FASE 3: UPSERT / SOSTITUZIONE (POST/api/v1/certificates/upsert)
Verifica corrispondenza passTypeIdentifier & teamIdentifier + WWDR G4/G6
Sostituisce firmatario .p12 attivo nel encrypted storagei pass iOS continuano sync

Importante: Rinnovi sempre sotto l'esatto stesso Pass Type ID (pass.com.yourbrand.*) e Apple Developer Team ID invece di creare un nuovo Pass Type ID da zero. Poiché iOS lega i pass installati alla coppia (passTypeIdentifier, teamIdentifier), rinnovare il certificato sullo stesso Pass Type ID permette a tutti i pass esistenti sugli iPhone e Apple Watch dei clienti di continuare a ricevere aggiornamenti push APNs con zero reinstallazioni richieste al cliente.

Procedura di rinnovo certificati a zero downtime

  1. 1
    Monitoraggio delle finestre di scadenza (Certificate Renewal Monitor): Passinstance esegue ogni giorno alle 02:00 un controllo programmato sui certificati attivi con validTo entro 30 giorni, inviando un'e-mail a proprietari e amministratori del workspace e mostrando gli avvisi in Impostazioni -> Wallet -> Certificati Apple.
  2. 2
    Generazione di un CSR di rinnovo: Apra il certificato in scadenza in Passinstance e scarichi un nuovo CSR (POST /api/v1/certificates/generate-csr).
  3. 3
    Emissione di un nuovo certificato sotto il Pass Type ID esistente: In Apple Developer Portal -> Identifiers -> Pass Type IDs, selezioni il Pass Type ID esistente, clicchi su Create Certificate, carichi il CSR e scarichi il nuovo pass.cer. (Apple consente certificati attivi sovrapposti sullo stesso Pass Type ID, così da poter completare la rotazione in sicurezza prima di revocare il certificato precedente.)
  4. 4
    Upsert del file pass.cer rinnovato in Passinstance: Carichi il file .cer firmato tramite POST /api/v1/certificates/upsert (multipart/form-data, specificando passTypeId, type: "TYPE_PASS" | "TYPE_NFC" ed eventuale pkeyId). Passinstance verifica la catena Apple WWDR G4/G6 e sostituisce il certificato di firma attivo.
  5. 5
    Verifica firma e push APNs: Emetta un pass di test (POST /api/v1/passes) e invii una notifica push (POST /api/v1/push-notifications/passes/:id) per confermare che sia la firma del bundle PKCS#7 sia la consegna HTTP/2 APNs vadano a buon fine.

Endpoint API per rinnovo e ciclo di vita dei certificati (Certificate Management API)

MetodoPercorso endpointPermesso richiestoDescrizione
GET/api/v1/certificatescertificates:readElenca i certificati del workspace e i relativi metadati (validFrom, validTo, passTypeIdentifier, teamIdentifier, type).
POST/api/v1/certificates/generate-csrcertificates:manageGenera una coppia di chiavi RSA (CertificatePkey) e restituisce un CSR PEM per la firma in Apple Developer.
POST/api/v1/certificates/upsertcertificates:manageCrea o sostituisce/rinnova atomicamente un certificato esistente a partire da un .cer firmato caricato (multipart/form-data).
GET/api/v1/certificates/:idcertificates:readIspeziona metadati X.509, date di validità e associazione del Pass Type ID.
DELETE/api/v1/certificates/:idcertificates:manageRimuove un record certificato superato o non utilizzato.

Esempio: eseguire l'upsert di un certificato .cer rinnovato

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

Risposta (201 Created / 200 OK):

JSON
{
  "id": "cert_8841a9b0-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "passTypeIdentifier": "pass.com.phenixroasters.loyalty",
  "teamIdentifier": "9A8B7C6D5E",
  "type": "TYPE_PASS",
  "validTo": "2027-12-31T23:59:59.000Z"
}

Rotazione automatica dei certificati intermedi Apple WWDR G4 e G6

Passinstance gestisce automaticamente i certificati intermedi Worldwide Developer Relations (WWDR) di Apple (G4 e G6) all'interno dell'archivio certificati PKCS#7 lato server (Apple Wallet Packager). Non è mai necessario caricare manualmente AppleWWDRCAG4.cer o AppleWWDRCAG6.cer: Passinstance legge l'Authority Key Identifier (AKI) del file pass.cer caricato e include il certificato intermedio WWDR corrispondente nella signature di ogni .pkpass.

Consulti Certificati Apple Wallet e Apple Wallet per i passaggi iniziali di configurazione.

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.