Panoramica: come funziona la sincronizzazione dei pass live
A differenza di biglietti PDF statici o codici a barre come immagini fisse, i pass Wallet digitali gestiti da Passinstance restano collegati dinamicamente al cloud dopo l'installazione. Ogni volta che cambia un attributo del pass, un saldo di meccanica (timbri, punti fedeltà, credito prepagato), il livello o il design del modello, Passinstance orchestra una Pipeline di propagazione Wallet asincrona che aggiorna la tessera live su iPhone, Apple Watch e dispositivi Android del cliente.
Ciclo di vita dello stato di propagazione Wallet (walletVoidStatus / WalletPropagationStatus)
Ogni record pass traccia lo stato di annullamento/propagazione attraverso le reti cloud Apple e Google tramite Pass.walletVoidStatus (WalletPropagationStatus):
| Enum di stato | Significato e stato operativo |
|---|---|
NONE | Il pass è appena stato creato oppure nessuna propagazione visibile nel Wallet è stata accodata. |
PENDING | Una modifica ai campi, al saldo della meccanica, allo stato void o al modello è stata salvata; in attesa di invio nella coda background job queue. |
QUEUED | Inviato nella coda worker in-memory cache/background job queue di propagazione Wallet per l'esecuzione verso APNs e Google REST. |
SUCCEEDED | La notifica push APNs è stata accettata dal gateway HTTP/2 Apple (200 OK) e/o la PATCH REST su Google Wallet ha avuto successo. |
FAILED | La propagazione ha riscontrato un errore upstream (es. certificato Apple Pass Type scaduto, token APNs revocato 410 Gone o limite quota API Google). |
Importante: Pubblicare una bozza del modello tramite
POST /api/v1/templates/:id/publishconpropagateUpdates: truedistribuisce i job di propagazione su tutti i pass attivi collegati a quel modello (filtrabili conactivePassesOnly: true). Esegua sempre primaGET /api/v1/templates/:id/publish-risk-checkper verificare modifiche critiche e potenziali impatti.
Endpoint API per l'aggiornamento dei pass
| Metodo | Percorso endpoint | Descrizione |
|---|---|---|
| PATCH | /api/v1/passes/:id | Aggiorna attributi personalizzati, stato, data di scadenza o payload codice a barre di un singolo pass e avvia la propagazione nel Wallet. |
| POST | /api/v1/passes/upsert-by-external-id | Crea o aggiorna in modo idempotente un pass esistente associato a (customerId, externalId) (supportato anche PUT /api/v1/passes/by-external-id/:externalId). |
| POST | /api/v1/batch-pass-operations/update | Aggiorna i passIds selezionati in un'unica richiesta batch (request payload) e accoda i job di propagazione. |
| POST | /api/v1/templates/:id/publish | Promuove una bozza di modello (request payload con propagateUpdates: true) e aggiorna i pass attivi di quel modello. |
Esempio: aggiornamento singolo pass e avvio della propagazione
PATCH /api/v1/passes/c41a8d20-6e11-4f3b-9a81-0029d81a4f10
{
"attributes": {
"points": 1450,
"tier": "Platinum",
"nextReward": "Free Espresso"
},
"expirationDate": "2027-12-31 23:59"
}
Risposta (200 OK):
{
"id": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"externalId": "cust_884910",
"serialNumber": "PI-8849-2026-X9",
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "QUEUED",
"updatedAt": "2026-11-15T14:22:10.114Z"
}
Esempio: aggiornamento batch di array pass (request payload)
POST /api/v1/batch-pass-operations/update
{
"operation": "update",
"passIds": [
"c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"9b2f1e44-8a10-4c92-a711-5530e91b2c01"
],
"updateData": {
"attributes": {
"seasonalOffer": "Winter Bonus Points"
}
}
}
Perché i tempi di sincronizzazione possono variare tra dispositivi
-
Modalità aereo e Consumo ridotto dati: I dispositivi iOS in Modalità aereo o Risparmio energetico posticipano il recupero APNs in background finché non torna la connettività Wi-Fi o cellulare.
-
Interruttore Aggiornamenti automatici: I clienti che hanno disattivato Aggiornamenti automatici sul retro del pass Apple Wallet devono trascinare verso il basso manualmente in Apple Wallet per scaricare l'ultimo bundle
.pkpass. -
Soppressione sui pass annullati: Per impostazione predefinita, i pass in stato
VOIDEDoEXPIREDbloccano i push marketing ordinari a meno cheupdateVoidedExpiredPasses: truenon sia abilitato sul modello.
Consulti Notifiche push, Visualizzare e aggiornare i pass e Versioni modello e pubblicazione per i flussi correlati.
