Skip to content
Guida del Centro assistenza · Aggiornamenti e notifiche Wallet
3 min di letturaVerificato 2026-11-16

Aggiornare pass esistenti

Scopri come le modifiche lato server inviano aggiornamenti silenti APNs Apple e patch REST Google Wallet.

In questa guida

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.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
PIPELINE DI AGGIORNAMENTO E PROPAGAZIONE WALLET
FASE 01 SORGENTI DI TRIGGER DELLE MODIFICHE
Singolo pass: PATCH/api/v1/passes/:id o POST/api/v1/passes/upsert-by-external-id
Batch su array: POST/api/v1/batch-pass-operations/update
Pubblicaz. modello: POST/api/v1/templates/:id/publish (propagateUpdates: true)
Scanner / POS: POST/api/v1/scans / POST/v1/pos/redeem / /api/v1/reader/redeem
FASE 02 COMMIT SU DATABASE E TRANSIZIONE STATO DI PROPAGAZIONE
1
Incrementa la revisione del pass e registra il log di audit pass audit log
2
Imposta walletVoidStatus (WalletPropagationStatus): NONEPENDINGQUEUED
3
Accoda il job di propagazione background job queue (coda wallet-propagation)
Registrazioni dispositivi Apple
FASE 03A
1
Apple Push Delivery invia push HTTP/ {} a ogni dispositivo registrato
2
iOS si risveglia e interroga:GET/v1/devices/.../registrations
3
iOS scarica il nuovo .pkpass firm.:GET/v1/passes/:typeId/:serial
Oggetto Cloud Google Wallet
FASE 03B uoto| | 1. Google Wallet Sync esegu
PATCH REST autenticata su walletobjects/v1/...
2
Google Cloud invia lo stato aggiornato ad Android tramite Google Play Services
FASE 04 AGGIORNAMENTO TELEMETRIA FINALE E STATO PROPAGAZIONE
walletVoidStatus (WalletPropagationStatus): SUCCEEDED o FAILED

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 statoSignificato e stato operativo
NONEIl pass è appena stato creato oppure nessuna propagazione visibile nel Wallet è stata accodata.
PENDINGUna modifica ai campi, al saldo della meccanica, allo stato void o al modello è stata salvata; in attesa di invio nella coda background job queue.
QUEUEDInviato nella coda worker in-memory cache/background job queue di propagazione Wallet per l'esecuzione verso APNs e Google REST.
SUCCEEDEDLa notifica push APNs è stata accettata dal gateway HTTP/2 Apple (200 OK) e/o la PATCH REST su Google Wallet ha avuto successo.
FAILEDLa 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/publish con propagateUpdates: true distribuisce i job di propagazione su tutti i pass attivi collegati a quel modello (filtrabili con activePassesOnly: true). Esegua sempre prima GET /api/v1/templates/:id/publish-risk-check per verificare modifiche critiche e potenziali impatti.

Endpoint API per l'aggiornamento dei pass

MetodoPercorso endpointDescrizione
PATCH/api/v1/passes/:idAggiorna 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-idCrea 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/updateAggiorna i passIds selezionati in un'unica richiesta batch (request payload) e accoda i job di propagazione.
POST/api/v1/templates/:id/publishPromuove 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

JSON
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):

JSON
{
  "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)

JSON
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 VOIDED o EXPIRED bloccano i push marketing ordinari a meno che updateVoidedExpiredPasses: true non sia abilitato sul modello.

Consulti Notifiche push, Visualizzare e aggiornare i pass e Versioni modello e pubblicazione per i flussi correlati.

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.