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.

Architettura di sistema: query sui pass, modifica e cambio modello
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,idempotencyKeyoiddel 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 InstalledoppureRemovedtra le registrazioni di dispositivi Apple Wallet (iOS) e Google Wallet (Android). -
Intervalli temporali: Filtri per intervallo su
createdAt,updatedAt,expirationDateelastScannedAt. -
Attributi personalizzati structured JSON (
attribute search index): Filtri ad alta velocità di contenimento e confronto su qualsiasi chiave dentropass.attributes(ad esempioattributes.memberTier = "VIP"oppureattributes.pointsBalance >= 1000).

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 aexternalIdsenza dover memorizzare esternamente gli UUID interni)
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
{
"attributes": {
"pointsBalance": 1450,
"memberTier": "Platinum"
},
"barcodeAltText": "44910-PLATINUM",
"expirationDate": "2028-12-31 23:59"
}
Risposta HTTP (200 OK)
{
"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:
| Endpoint | Ambito e dati restituiti | |||
|---|---|---|---|---|
GET /api/v1/passes/:id/history | Restituisce in ordine cronologico le modifiche a campi e attributi (previousValue, newValue, changedBy, `source: 'API' \ | 'SCANNER' \ | 'DASHBOARD' \ | 'WORKFLOW', timestamp`). |
GET /api/v1/passes/:id/timeline | Restituisce 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
/api/v1/passes/pass_01j8k9m2n3p4q5r6/timeline
{
"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
{
"preserveAttributes": true,
"attributeOverrides": {
"vipLoungeAccess": "Unlimited"
},
"pushUpdateImmediately": true
}
Importante: Per trasferire un pass verso
:targetTemplateIdsenza soluzione di continuità sui dispositivi Apple Wallet, sia il modello di origine sia il modello di destinazione devono condividere lo stesso ApplepassTypeIdentifier(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.
