Skip to content
Guida del Centro assistenza · Gestione passFase di onboarding 3
3 min di letturaVerificato 2026-11-16

Visualizzare e aggiornare i pass

Cerca pass tramite viste salvate e filtri E/O, controlla i dispositivi associati e modifica i dati titolare.

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 ingrandito1 / 2
Elementi chiave dell'interfaccia

Elenco pass emessi e azioni per riga (Ingrandito)

Apri Passes per verificare i pass di test, filtrare per stato o installazione e usare QR, dettagli, modifica e push.

Panoramica

Apra Pass nella Dashboard (nella directory globale del workspace oppure all'interno della scheda Pass di un singolo modello) o interroghi /api/v1/passes per esaminare, filtrare, verificare, aggiornare e migrare in tempo reale i record dei pass emessi. Ogni modifica ai campi o all'assegnazione del modello di un pass viene sincronizzata automaticamente sui dispositivi Apple Wallet e Google Wallet registrati.

Filtri di ricerca pass e telemetria delle righe
Filtri di ricerca pass e telemetria delle righe

Architettura di sistema: query sui pass, modifica e cambio modello

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
QUERY PASS, PATCH E CAMBIO MODELLO
FASE 01 BUILDER FILTRI DASHBOARD / REST API (/api/v1/passes)
Ricerca e filtri: GET/api/v1/passes?templateId=...&status=ACTIVE&...
Aggiornamento parz.:PATCH/api/v1/passes/:id
Audit e timeline: GET/api/v1/passes/:id/history & /timeline
Cambio modello: POST/api/v1/passes/:id/switch-template/:targetTemplateId
FASE 02 MOTORE DI QUERY DATABASE E INDICIZZAZIONE ATTRIBUTI GIN
Indici relazionali su (customerId, templateId, status, externalId)
Filtraggio structured JSON sotto il millisecondo tramite indice GIN attribute search index
Aggiunge voci immutabili di diff campi nella timeline pass audit log e Scan
FASE 03 PROPAGAZIONE PUSH WALLET (WalletPropagationStatus)
Transizione stato propagazione: PENDINGQUEUEDSUCCEEDED
Apple Wallet: Invia push di risveglio HTTP/2 APNsscarica nuovo .pkpass
Google Wallet: Esegue REST PATCH sulla risorsa cloud walletobjects

1. Ricerca e filtraggio dei pass (GET /api/v1/passes)

Nella Dashboard, apra Filtri per combinare Gruppi di condizioni AND / OR tra colonne di sistema e attributi structured JSON personalizzati, quindi salvi le ricerche frequenti come Viste salvate:

  • Identità e chiavi: serialNumber, externalId, bundleId, idempotencyKey o id del pass.
  • Ciclo di vita e stato: status (pass status), lifecycleStatus (PassLifecycleStatus), walletVoidStatus (WalletPropagationStatus) e stato degli artefatti (appleArtifactStatus, googleArtifactStatus).
  • Stato di installazione Wallet: Installed, Not Installed oppure Removed tra le registrazioni di dispositivi Apple Wallet (iOS) e Google Wallet (Android).
  • Intervalli temporali: Filtri per intervallo su createdAt, updatedAt, expirationDate e lastScannedAt.
  • Attributi personalizzati structured JSON (attribute search index): Filtri ad alta velocità di contenimento e confronto su qualsiasi chiave dentro pass.attributes (ad esempio attributes.memberTier = "VIP" oppure attributes.pointsBalance >= 1000).
Pannello filtri avanzati con costruttore condizioni AND/OR
Pannello filtri avanzati con costruttore condizioni AND/OR

Esempio: interrogare i pass e cercare tramite External ID

  • GET /api/v1/passes?templateId=tmpl_01hxyz987654321&status=ACTIVE&externalId=crm_usr_44910&page=1&limit=25
  • GET /api/v1/passes/by-external-id/crm_usr_44910 (restituisce direttamente il pass attivo non eliminato corrispondente a externalId senza dover memorizzare esternamente gli UUID interni)
Header
X-API-Key <API_KEY>

2. Aggiornamento di un singolo pass (PATCH /api/v1/passes/:id)

L'aggiornamento di un pass integra i nuovi valori dentro attributes, adegua expirationDate o barcodeValue e accoda subito un aggiornamento push verso tutti i dispositivi su cui il pass è installato. Se un campo modificato ha un changeMessage contenente %@ configurato sul modello, Apple Wallet mostra un avviso nativo nella schermata di blocco.

Richiesta HTTP

PATCH /api/v1/passes/pass_01j8k9m2n3p4q5r6 Header: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "attributes": {
    "pointsBalance": 1450,
    "memberTier": "Platinum"
  },
  "barcodeAltText": "44910-PLATINUM",
  "expirationDate": "2028-12-31 23:59"
}

Risposta HTTP (200 OK)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01j8k9m2n3p4q5r6",
    "serialNumber": "PI-GOLD-2026-44910",
    "externalId": "crm_usr_44910",
    "bundleId": null,
    "status": "ACTIVE",
    "lifecycleStatus": "ACTIVE",
    "walletVoidStatus": "QUEUED",
    "attributes": {
      "firstName": "Marcus",
      "lastName": "Vance",
      "email": "marcus.vance@example.com",
      "pointsBalance": 1450,
      "memberTier": "Platinum"
    },
    "updatedAt": "2026-11-15T17:30:00.000Z"
  },
  "statusCode": 200
}

3. Verifica dello storico e della timeline eventi del pass

Passinstance mantiene due flussi di audit complementari per ciascun record pass:

EndpointAmbito e dati restituiti
GET /api/v1/passes/:id/historyRestituisce in ordine cronologico le modifiche a campi e attributi (previousValue, newValue, changedBy, `source: 'API' \'SCANNER' \'DASHBOARD' \'WORKFLOW', timestamp`).
GET /api/v1/passes/:id/timelineRestituisce il flusso unificato di ciclo di vita e interazione, combinando creazione del pass, eventi di consegna e-mail/SMS, installazioni su dispositivi Apple/Google, validazioni scanner, rettifiche saldo e notifiche push.

Esempio: recuperare la timeline del pass

GET /api/v1/passes/pass_01j8k9m2n3p4q5r6/timeline
JSON
{
  "success": true,
  "data": {
    "passId": "pass_01j8k9m2n3p4q5r6",
    "events": [
      {
        "eventId": "evt_03",
        "type": "ATTRIBUTE_UPDATED",
        "summary": "pointsBalance changed from 500 to 1450",
        "actor": "api_key:pi_live_99a8",
        "createdAt": "2026-11-15T17:30:00.000Z"
      },
      {
        "eventId": "evt_02",
        "type": "WALLET_INSTALLED",
        "platform": "APPLE_WALLET",
        "deviceLibraryIdentifier": "dlib_8841209a",
        "createdAt": "2026-11-15T15:10:05.000Z"
      },
      {
        "eventId": "evt_01",
        "type": "PASS_CREATED",
        "summary": "Pass issued via REST API",
        "createdAt": "2026-11-15T15:04:12.000Z"
      }
    ]
  },
  "statusCode": 200
}

4. Migrazione live del modello (POST /api/v1/passes/:id/switch-template/:targetTemplateId)

Quando un cliente passa a un nuovo design di livello oppure transita tra programmi stagionali, è possibile migrare un pass esistente verso un altro modello PUBLISHED senza modificare id, serialNumber, authenticationToken o le registrazioni attive dei dispositivi.

POST /api/v1/passes/pass_01j8k9m2n3p4q5r6/switch-template/tmpl_platinum_vip_999 Header: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "preserveAttributes": true,
  "attributeOverrides": {
    "vipLoungeAccess": "Unlimited"
  },
  "pushUpdateImmediately": true
}

Importante: Per trasferire un pass verso :targetTemplateId senza soluzione di continuità sui dispositivi Apple Wallet, sia il modello di origine sia il modello di destinazione devono condividere lo stesso Apple passTypeIdentifier (certificato Pass Type ID). Se il modello di destinazione utilizza un Pass Type ID diverso, iOS lo considera come una tessera distinta invece che una sostituzione visiva in loco.

Per le transizioni di stato e le regole di annullamento, consulti Ciclo di vita e stati del pass. Per aggiornamenti su più record contemporaneamente, consulti Operazioni di massa.

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.