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

Operazioni in blocco

Esegui azioni massive su segmenti filtrati: aggiornamenti multipli, annullamento, eliminazione ed esportazioni.

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 ingrandito
Elementi chiave dell'interfaccia

Scheda Passes e Azioni massive (Ingrandito)

Dopo l'import massivo, usa Passes, filtri e Bulk actions per ispezionare o aggiornare le card generate.

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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
OPERAZIONI IN BLOCCO SUI PASS E PROPAGAZIONE WALLET
FASE 01 BARRA STRUMENTI IN BLOCCO DASHBOARD / API (Batch Operations API)
Selezione coorte (StickySelectionToolbar / Pannello filtri / ID dei pass)
POST/api/v1/batch-pass-operations/update (operation: "update")
POST/api/v1/batch-pass-operations/upsert (Indicizzato su externalId)
POST/api/v1/batch-pass-operations/activate (operation: "activate")
POST/api/v1/batch-pass-operations/deactivate (operation: "deactivate")
POST/api/v1/batch-pass-operations/delete (request payload)
POST/api/v1/batch-pass-operations/validate (Controllo pre-flight payload)
FASE 02 MOTORE DI VALIDAZIONE ED ESECUZIONE ISOLATA PER ELEMENTO
Rimuove le chiavi protette del tenant (customerId, tenantId, createdBy)
Pre-valida gli attributi con preValidateAttributes (salta obbligatori su upd)
Normalizza gli attributi con normalizeAttributes
Restituisce request payload: { success, data, message, errors, warnings }
FASE 03A CODA WORKER HTTP/2 APNs CON THROTTLING
Coda job: push-notifications
Pool connessioni HTTP/2 persistenti
Rate limiting evita errori Apple 429
Push silenziosa risveglia il device
FASE 03B PROPAGAZIONE CLASSE GOOGLE WALLET
Modifica modello: PATCH Issuer Class
Sync istantanea su TUTTI gli Android
PATCH su singolo Pass Object per attributi dinamici specifici

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) e not_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" AND pointsBalance < 500 AND expirationDate < 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. 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.

  1. 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/apns mantiene 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

OperazioneEndpoint APIDTO e comportamento
Creazione batchPOST /api/v1/batch-pass-operations/createrequest payload (passes[], max 1.000 elementi). Emette nuovi pass con externalId e bundleId opzionali.
Aggiornamento batchPOST /api/v1/batch-pass-operations/updaterequest payload (operation: "update", passIds[], updateData, bundleOptions opzionale).
Upsert batchPOST /api/v1/batch-pass-operations/upsertrequest payload (operation: "upsert", passData[]) con chiave sul tenant (customerId, externalId).
Attivazione batchPOST /api/v1/batch-pass-operations/activaterequest payload (operation: "activate", passIds[]) che porta i pass allo stato ACTIVE.
Disattivazione (Annullamento) batchPOST /api/v1/batch-pass-operations/deactivaterequest payload (operation: "deactivate", passIds[]) che porta i pass allo stato SUSPENDED / INACTIVE e invalida i codici a barre.
Eliminazione batchPOST /api/v1/batch-pass-operations/deleterequest payload (passIds[]) che porta i pass attraverso DELETING -> eliminazione logica (archivedAt: new Date()).
Creazione bundle batchPOST /api/v1/bundles/batch-createRaggruppa gli ID dei pass selezionati in contenitori pass bundle condivisi (Pass.bundleId, fino a 10 pass per bundle).

Importante: Ispeziona sempre errors e warnings in request payload. Quando validateBatchOperation rileva righe non valide, il controller restituisce success: false con diagnostica dettagliata per singolo elemento in errors[].


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

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)

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

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)

JSON
{
  "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": [...] } tramite request payload)

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 segnapostoCanonico / AliasEsempio di output risolto
{passDownloadUrl}Canonicohttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{smartLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{downloadUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{walletDownloadUrl}Alias dinamicoLink 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:

VariabileDescrizione
{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. 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. 2
    Struttura standard degli errori: gli elementi falliti vengono segnalati in errors[] con passId, messaggio error e errorCode:
JSON
{
     "passId": "pass_01j8k9m2n3p4q5r6",
     "error": "Attribute 'pointsBalance' must be a valid number",
     "errorCode": "ATTR_VALIDATION"
   }
  1. 3
    Audit logging del workspace: ogni operazione in blocco genera una voce nel pass audit log e 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.

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.