Panoramica
Dopo aver individuato una coorte mirata di pass nella Dashboard utilizzando i Filtri rapidi o il pannello di filtro avanzato AND/OR (StickySelectionToolbar), usa il menu Azioni in blocco nella barra degli strumenti dei Pass — oppure richiama la Batch Operations API (/api/v1/batch-pass-operations/*) tramite REST API — per eseguire operazioni strutturate su array fino a 1.000 pass per chiamata. A differenza dei caricamenti multipart di file CSV (/api/v1/batch-processing), /api/v1/batch-pass-operations/* elabora direttamente payload JSON e restituisce errors e warnings per singolo elemento nel request payload.
Quando aggiorni migliaia o decine di migliaia di pass emessi simultaneamente, Passinstance disaccoppia le modifiche sul database dall'invio delle notifiche push verso i wallet mobili. Le modifiche vengono salvate immediatamente nel database, mentre gli aggiornamenti vengono trasmessi ai dispositivi Apple Wallet tramite connessioni HTTP/2 APNs in pool e con rate limiting, e ai dispositivi Google Wallet tramite propagazione istantanea della Issuer Class o patch REST sui singoli Pass Object.
Architettura di sistema: operazioni in blocco, throttling delle code e propagazione ai wallet
Filtraggio delle coorti di pass di destinazione
Prima di eseguire operazioni in blocco, gli amministratori isolano la coorte esatta di destinatari da modificare:
Filtri rapidi e pannello di filtro avanzato AND/OR
Nella Dashboard, nella sezione Pass (/passes):
-
Filtro Modello: limita le azioni a uno specifico modello di pass o al design di una tessera di campagna.
-
Filtro Stato: filtra per stato del ciclo di vita (
ACTIVE,INACTIVE,SUSPENDED,EXPIRED,VOIDED). -
Filtro Stato dispositivo: distingue tra
active_only(installato su almeno un dispositivo),inactive_only(disinstallato) enot_registered(link di download non ancora riscattati). -
Pannello di ricerca avanzata (
Advanced Filter panel): combina più attributi tramite logica AND/OR (ad es.tier == "Gold"ANDpointsBalance < 500ANDexpirationDate < 2027-01-01). -
Barra di selezione persistente (
StickySelectionToolbar):
- Fai clic sulla casella principale per selezionare la pagina corrente (fino a 100 pass). - Fai clic sul banner di conferma per selezionare tutti i pass corrispondenti in tutte le pagine (ad es., "Seleziona tutti i 4.850 pass corrispondenti a questo filtro").
Selezione coorte via API
Tramite REST API, risolvi gli UUID dei pass di destinazione utilizzando POST /api/v1/passes/query-builder oppure POST /api/v1/passes/search, quindi passa gli ID ottenuti a /batch-pass-operations/*.
Aggiornamento di migliaia di pass emessi
Aggiornare grandi parchi di pass già emessi richiede un equilibrio tra la capacità di scrittura del database e i rigorosi limiti di connessione dei gateway di notifica push dei wallet mobili.
Operazioni dirette su array vs. importazione batch CSV
Passinstance offre due percorsi distinti per gli aggiornamenti massivi in base al volume:
-
1
Operazioni dirette su array JSON (
POST /api/v1/batch-pass-operations/update):
- Ideali fino a 1.000 pass per richiesta HTTP. - Accettano un array di passIds e un unico dizionario updateData. - Risposta HTTP sincrona che restituisce stato individuale, errori e avvisi per ciascun pass.
-
2
Pipeline batch CSV asincrona (
/api/v1/batch-processing):
- Ideale da 1.000 a oltre 100.000 pass. - Carica un file CSV contenente identificatori univoci (externalId o serialNumber) e gli attributi modificati. - Imposta l'operazione su UPDATE_PASSES o UPSERT. - I worker della coda di job in background elaborano le righe in modo asincrono in transazioni database delimitate da 50 righe, con tracciamento dell'avanzamento in tempo reale e registri dei risultati scaricabili (result.csv).
Throttling HTTP/2 APNs di Apple Wallet e pooling delle connessioni
Quando aggiorni pass Apple Wallet, Passinstance invia notifiche push che invitano i dispositivi iOS a risvegliarsi in modo silenzioso e a scaricare il bundle .pkpass aggiornato dalla API di Passinstance:
-
Notifiche push silenziose: le notifiche dei pass vengono inviate con
content-available: 1. Non mostrano popup invasivi sulla schermata di blocco a meno che non siano configurati messaggi localizzati di modifica campo (ad es. "Il tuo gate è cambiato in B12"). -
Flussi persistenti HTTP/2: il servizio
@passinstance/apnsmantiene connessioni HTTP/2 persistenti in pool verso i server push di Apple (api.push.apple.com:443). Anziché chiudere e ricreare handshake TLS per ogni destinatario, i flussi vengono multiplexati sulle connessioni attive. -
Rate limiting adattivo e throttling delle code:
- Le notifiche in uscita transitano attraverso code di job in background (push-notifications, individual-push-notifications, silent-push-notifications). - Notification Rate Limiter e Notification Deduplication monitorano il flusso delle risposte di Apple. - Se APNs restituisce 429 TooManyRequests o segnala backpressure a livello di connessione, i worker riducono la concorrenza e applicano un backoff esponenziale, evitando l'invalidazione dei token e l'inserimento dell'IP in blacklist.
Aggiornamenti di Classe Google Wallet vs. PATCH su Oggetto
Google Wallet adotta un'architettura gerarchica che separa la Pass Class (la definizione principale del modello) dal Pass Object (l'istanza del singolo titolare):
-
Aggiornamenti visivi e di campo a livello di modello (Issuer Class):
Quando viene pubblicata una modifica globale su un modello (ad es. la sostituzione del logo nell'intestazione, del colore di sfondo o delle condizioni del programma) rivolta a tutte le tessere senza testo personalizzato (!hasPersonalizedMessage), Passinstance invoca Google Wallet class sync in template.service.ts. Questa operazione invia un'unica richiesta REST PATCH alla Google Wallet API per aggiornare la Issuer Class. Poiché ogni pass Google Wallet emesso fa riferimento a tale Classe padre, i server cloud di Google propagano istantaneamente l'aggiornamento a tutti i pass Android attivi simultaneamente, senza generare migliaia di singole richieste API.
-
Aggiornamenti di attributi specifici del titolare (Pass Object):
Quando gli attributi variano da un pass all'altro (come saldi punti individuali, passaggi di livello o nomi personalizzati), Passinstance esegue singole chiamate HTTP PATCH sullo specifico Google Wallet Pass Object (POST /batch-pass-operations/update).
Validazione degli attributi e regole di sicurezza
Il servizio di aggiornamento batch (batch-pass-operations.service.ts) garantisce una rigorosa integrità dei dati:
-
Isolamento del tenant: i campi protetti (
customerId,tenantId,createdBy,templateId) vengono rimossi automaticamente dai payload in ingresso. Gli aggiornamenti non possono alterare la proprietà del pass né riassegnare i modelli padre. -
Validazione parziale degli attributi (
preValidateAttributes): durante l'aggiornamento di pass esistenti (isUpdate = true), i controlli sui campi obbligatori vengono saltati. Puoi aggiornare una singola proprietà personalizzata (ad es.pointsBalance) senza reinviare i campi invariati esistenti. -
Normalizzazione degli attributi: le stringhe vengono ripulite dagli spazi iniziali e finali, i numeri vengono convertiti in float/int e le date vengono normalizzate in formato ISO-8601 UTC.
Operazioni in blocco supportate su Dashboard e API
| Operazione | Endpoint API | DTO e comportamento |
|---|---|---|
| Creazione batch | POST /api/v1/batch-pass-operations/create | request payload (passes[], max 1.000 elementi). Emette nuovi pass con externalId e bundleId opzionali. |
| Aggiornamento batch | POST /api/v1/batch-pass-operations/update | request payload (operation: "update", passIds[], updateData, bundleOptions opzionale). |
| Upsert batch | POST /api/v1/batch-pass-operations/upsert | request payload (operation: "upsert", passData[]) con chiave sul tenant (customerId, externalId). |
| Attivazione batch | POST /api/v1/batch-pass-operations/activate | request payload (operation: "activate", passIds[]) che porta i pass allo stato ACTIVE. |
| Disattivazione (Annullamento) batch | POST /api/v1/batch-pass-operations/deactivate | request payload (operation: "deactivate", passIds[]) che porta i pass allo stato SUSPENDED / INACTIVE e invalida i codici a barre. |
| Eliminazione batch | POST /api/v1/batch-pass-operations/delete | request payload (passIds[]) che porta i pass attraverso DELETING -> eliminazione logica (archivedAt: new Date()). |
| Creazione bundle batch | POST /api/v1/bundles/batch-create | Raggruppa gli ID dei pass selezionati in contenitori pass bundle condivisi (Pass.bundleId, fino a 10 pass per bundle). |
Importante: Ispeziona sempre
errorsewarningsinrequest payload. QuandovalidateBatchOperationrileva righe non valide, il controller restituiscesuccess: falsecon diagnostica dettagliata per singolo elemento inerrors[].
Riferimento programmatico alle operazioni batch sui pass (request payload)
1. Upsert batch di pass (POST /api/v1/batch-pass-operations/upsert)
Ideale per sincronizzazioni CRM o ricalcoli dei livelli fedeltà basati su externalId:
Richiesta HTTP
POST /api/v1/batch-pass-operations/upsert Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"operation": "upsert",
"passData": [
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44910",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"pointsBalance": 1800,
"memberTier": "Platinum"
}
},
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44911",
"attributes": {
"firstName": "Hannah",
"lastName": "Abbott",
"pointsBalance": 250,
"memberTier": "Silver"
}
}
]
}
Risposta HTTP (200 OK)
{
"success": true,
"data": [
{
"id": "pass_01j8k9m2n3p4q5r6",
"externalId": "crm_usr_44910",
"serialNumber": "PI-GOLD-2026-44910",
"passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6"
},
{
"id": "pass_01j8k9m9z8y7x6w5",
"externalId": "crm_usr_44911",
"serialNumber": "PI-GOLD-2026-44911",
"passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m9z8y7x6w5"
}
],
"message": "Successfully upserted 2 passes",
"errors": [],
"warnings": []
}
2. Aggiornamento batch di pass (POST /api/v1/batch-pass-operations/update)
Aggiorna i passIds selezionati con un dizionario updateData condiviso e bundleOptions opzionali:
POST /api/v1/batch-pass-operations/update Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"operation": "update",
"passIds": [
"pass_01j8k9m2n3p4q5r6",
"pass_01j8k9m9z8y7x6w5"
],
"updateData": {
"expirationDate": "2028-03-31T23:59:59Z",
"attributes": {
"seasonalOffer": "2x Winter Bonus Points"
}
}
}
Risposta HTTP (200 OK)
{
"success": true,
"data": [
{
"id": "pass_01j8k9m2n3p4q5r6",
"status": "ACTIVE",
"updatedAt": "2026-11-16T12:00:00.000Z"
},
{
"id": "pass_01j8k9m9z8y7x6w5",
"status": "ACTIVE",
"updatedAt": "2026-11-16T12:00:00.000Z"
}
],
"message": "Successfully updated 2 passes",
"errors": [],
"warnings": []
}
3. Attivazione, disattivazione o eliminazione batch di pass
-
Attivazione:
POST /api/v1/batch-pass-operations/activate({ "operation": "activate", "passIds": [...] }) -
Disattivazione:
POST /api/v1/batch-pass-operations/deactivate({ "operation": "deactivate", "passIds": [...] }) -
Eliminazione:
POST /api/v1/batch-pass-operations/delete({ "passIds": [...] }tramiterequest payload)
Integrazione con la consegna: quale segnaposto inserisce il link del pass? ({passDownloadUrl})
Quale segnaposto inserisce il link del pass?
Quando fai seguire alle operazioni in blocco notifiche automatiche via e-mail o SMS, Passinstance mette a disposizione un motore flessibile di sostituzione dei segnaposto (pass-url-placeholder.util.ts). Il token segnaposto canonico è {passDownloadUrl}.
Segnaposto canonico e alias supportati
Il segnaposto ufficiale e canonico è {passDownloadUrl}. Passinstance supporta inoltre i seguenti alias retrocompatibili:
| Token segnaposto | Canonico / Alias | Esempio di output risolto |
|---|---|---|
{passDownloadUrl} | Canonico | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{smartLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{downloadUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{walletDownloadUrl} | Alias dinamico | Link contestuale che reindirizza in base al sistema operativo del client |
Flessibilità di formattazione: Passinstance normalizza automaticamente la sintassi a doppie parentesi graffe
{{passDownloadUrl}}, snake_case{pass_download_url}e PascalCase{PassDownloadUrl}nel token canonico.
Pulsanti di azione diretta per i Wallet e flag condizionali
Per modelli e-mail HTML responsive, puoi inserire pulsanti Wallet diretti a un solo tocco invece di affidarti esclusivamente alla pagina intermedia PassFlow:
| Variabile | Descrizione |
|---|---|
{appleWalletUrl} | Flusso di download binario .pkpass diretto che avvia l'installazione nativa in Apple Wallet su Safari iOS. |
{googleWalletUrl} | Deep link diretto Aggiungi a Google Wallet (https://pay.google.com/gp/v/save/...). |
{samsungWalletUrl} | Deep link diretto di salvataggio su Samsung Wallet. |
{walletButtonText} | Etichetta del pulsante sensibile al contesto ("Aggiungi ad Apple Wallet", "Salva in Google Wallet" o "Scarica il mio pass"). |
{showAppleWalletButton} | Flag booleano (true/false) che indica se gli asset Apple Wallet sono configurati. |
{showGoogleWalletButton} | Flag booleano che indica se l'integrazione Google Wallet è attiva. |
Errori parziali, gestione delle eccezioni e audit logging
Quando esegui operazioni batch, le richieste non falliscono interamente se solo un sottoinsieme di elementi presenta errori:
-
1
Isolamento degli errori per elemento: in
updateBatchPasses, ogni pass viene elaborato all'interno di un blocco try-catch isolato. Un errore alla riga 42 (ad es. formato data non valido) non impedisce alle righe 1–41 o 43–100 di andare a buon fine. -
2
Struttura standard degli errori: gli elementi falliti vengono segnalati in
errors[]conpassId, messaggioerroreerrorCode:
{
"passId": "pass_01j8k9m2n3p4q5r6",
"error": "Attribute 'pointsBalance' must be a valid number",
"errorCode": "ATTR_VALIDATION"
}
-
3
Audit logging del workspace: ogni operazione in blocco genera una voce nel
pass audit loge nel registro di audit del workspace (GET /api/v1/audit-log/export.csv), registrando ID dell'attore, indirizzo IP, tipo di operazione, numero di elementi interessati e timestamp.
Per le importazioni batch basate su file CSV, consulta Creazione massiva di pass. Per l'annullamento massivo su un intero modello, consulta Ciclo di vita e stati del pass.
