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

Creazione massiva di pass

Carica file CSV via Operazioni in blocco o importazione FTP/SFTP, mappa le colonne e monitora il processo.

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

Pannello lavori di importazione batch (Zoom)

Avvia un «New import job» dalla panoramica del modello e monitora le elaborazioni CSV in corso, fallite e completate.

Panoramica

Quando devi registrare centinaia o centinaia di migliaia di titolari simultaneamente, Passinstance offre una pipeline asincrona e tollerante ai guasti per l'importazione batch CSV, basata sulla Batch Jobs API (/api/v1/batch-processing) e su code worker di job in background supportate da cache in memoria. Gli operatori possono caricare fogli di calcolo UTF-8 dalla Dashboard (Operazioni in blocco -> Importa pass), avviare Importazioni FTP/SFTP automatizzate oppure orchestrare la pipeline CSV in 6 fasi in modo programmatico tramite REST API.

Contatori dei job di importazione batch e CTA per nuova importazione
Contatori dei job di importazione batch e CTA per nuova importazione

Architettura di sistema: emissione batch CSV e pipeline worker per job in background

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
EMISSIONE BATCH CSV E PIPELINE WORKER ASINCRONA
FASE 01 CARICAMENTO CSV DASHBOARD / API (Batch Jobs API)
1
GET/api/v1/batch-processing/templates/:templateId/sample-csv
2
POST/api/v1/batch-processing (Upload CSV UTF-8 multipart)
3
POST/api/v1/batch-processing/templates/:templateId/field-mapping-recommendations
FASE 02 MAPPATURA DELLO SCHEMA E VALIDAZIONE PRE-FLIGHT DRY-RUN
4
PUT/api/v1/batch-processing/:id/field-mapping (Collega colonnechiavi)
5
POST/api/v1/batch-processing/:id/validate
Verifica proprietà personalizzate obbligatorie, date ISO, numeri, externalId
Segnala errori di sintassi o schema riga per riga prima della scrittura DB
FASE 03 PIPELINE WORKER ASINCRONA (cache in memoria)
Elabora in streaming i blocchi CSV validati in transazioni delimitate
Genera record Pass, serialNumber, authenticationToken e smart link
Compila il registro scaricabile: GET/api/v1/batch-processing/:id/result.csv

Checklist dei prerequisiti

Prerequisiti: Prima di avviare un job di importazione batch CSV, verifica i seguenti requisiti:

1. Il Template di destinazione deve trovarsi nello stato PUBLISHED.

2. Il file CSV deve essere codificato in UTF-8 senza delimitatori malformati o virgolette non chiuse.

3. Includi le colonne email e/o phone se prevedi di inviare automaticamente i link di download dei pass tramite campagne del Delivery Center al termine della generazione.

4. Configura l'origine dell'External ID nelle Impostazioni del modello (externalId) se desideri una deduplicazione idempotente tra importazioni ripetute.

Flusso di importazione CSV passo dopo passo (Bulk Pass Wizard)

Nella Dashboard, alla voce Batch -> Elaborazione batch (/batch-processing), la procedura guidata accompagna gli operatori attraverso cinque fasi (Modello -> Carica CSV -> Mappa campi -> Opzioni di invio (opzionale) -> Elabora):

  1. 1
    Modello: scegli il modello PUBLISHED / PRODUCTION di destinazione (oppure apri Pass -> Importa direttamente dal modello).
  2. 2
    Carica CSV: trascina un file CSV UTF-8 oppure scarica il CSV di esempio dinamico (GET /api/v1/batch-processing/templates/:templateId/sample-csv) precompilato con intestazioni corrispondenti alle proprietà personalizzate e ai campi di sistema del modello (externalId, expirationDate, ecc.).
  3. 3
    Mappa campi: esamina i suggerimenti automatici di mappatura delle colonne con punteggio di affidabilità (POST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendations) che collegano intestazioni (ad es. Customer_ID, First_Name) a externalId o alle chiavi attributes.*.
  4. 4
    Opzioni di invio (quando abilitate): seleziona un modello di consegna E-mail/SMS se i nuovi pass devono essere inviati automaticamente al completamento.
  5. 5
    Elabora: valida e avvia il job nella coda in background (stati del job batch: NEW, READY_TO_RUN, INTEGRATION_MAPPING_COMPLETE, SENDOUT_PENDING, RUNNING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELLED, PAUSED), quindi scarica /result.csv contenente tutti i serialNumber, externalId, bundleId e link di download generati.

Riferimento REST API per l'elaborazione batch (Batch Jobs API)

Tutti gli endpoint per i job batch CSV sono esposti sotto /api/v1/batch-processing (con supporto ai tipi di job batch CREATE_PASSES, UPDATE_PASSES, DELETE_PASSES, IMPORT_DATA, EXPORT_DATA, MIGRATION e alle sorgenti dati batch CSV_UPLOAD, API, SEGMENT, QUERY, MANUAL):

FaseMetodo HTTP ed endpointScopo
1. CSV di esempioGET /api/v1/batch-processing/templates/:templateId/sample-csvScarica un modello di intestazioni CSV UTF-8 dinamico adattato alle proprietà personalizzate del modello.
2. Caricamento CSVPOST /api/v1/batch-processingCarica un file CSV multipart o una definizione JSON di job batch (status: NEW / READY_TO_RUN).
3. Mappatura automaticaPOST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendationsAnalizza le intestazioni delle colonne CSV e restituisce suggerimenti di mappatura degli attributi con punteggio di affidabilità.
4. Salvataggio mappaturaPUT /api/v1/batch-processing/:id/field-mappingSalva sul job il dizionario confermato di mappatura tra colonne CSV e attributi.
5. Validazione dry-runPOST /api/v1/batch-processing/:id/validateEsegue una validazione non distruttiva delle righe CSV e restituisce avvisi ed errori a livello di riga.
6. Avvio workerPOST /api/v1/batch-processing/:id/startAccoda il job del worker in background (status: RUNNING) per emettere i pass in modo asincrono.
7. Esportazione risultatiGET /api/v1/batch-processing/:id/result.csvTrasmette in streaming un report CSV con l'aggiunta di passId, serialNumber, link di download e stato per ciascuna riga.

Esempio: richiedere i suggerimenti di mappatura dei campi

POST /api/v1/batch-processing/templates/tmpl_01hxyz987654321/field-mapping-recommendations Header: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "csvHeaders": [
    "Customer_ID",
    "First_Name",
    "Last_Name",
    "Loyalty_Points",
    "Card_Expiry"
  ]
}

Risposta HTTP (200 OK)

JSON
{
  "success": true,
  "data": {
    "recommendations": [
      { "csvColumn": "Customer_ID", "targetField": "externalId", "confidence": 0.98, "matchType": "SYSTEM" },
      { "csvColumn": "First_Name", "targetField": "attributes.firstName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Last_Name", "targetField": "attributes.lastName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Loyalty_Points", "targetField": "attributes.pointsBalance", "confidence": 0.89, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Card_Expiry", "targetField": "expirationDate", "confidence": 0.94, "matchType": "SYSTEM" }
    ]
  },
  "statusCode": 200
}

Esempio: confermare la mappatura dei campi e validare il job

PUT /api/v1/batch-processing/job_batch_77123/field-mapping Header: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "duplicateStrategy": "UPSERT_BY_EXTERNAL_ID",
  "mappings": {
    "Customer_ID": "externalId",
    "First_Name": "attributes.firstName",
    "Last_Name": "attributes.lastName",
    "Loyalty_Points": "attributes.pointsBalance",
    "Card_Expiry": "expirationDate"
  }
}

Quindi valida e avvia il worker della coda di job in background:

POST /api/v1/batch-processing/job_batch_77123/validate POST /api/v1/batch-processing/job_batch_77123/start

JSON
{
  "success": true,
  "data": {
    "id": "job_batch_77123",
    "status": "RUNNING",
    "jobType": "CREATE_PASSES",
    "dataSource": "CSV_UPLOAD",
    "totalRows": 5000,
    "processedRows": 0
  },
  "statusCode": 200
}

Risoluzione dei problemi e domande frequenti

Come posso verificare quando un job di elaborazione massiva fallisce?

Quando un'importazione batch CSV asincrona riscontra un problema, ispeziona lo stato e i log del job dalla Dashboard oppure tramite la REST API:

  1. 1
    Pannello Job nella Dashboard: vai su Batch -> Elaborazione batch (/batch-processing). I job completati con errori mostrano il badge Completato con errori (COMPLETED_WITH_ERRORS), mentre i job interrotti mostrano Fallito (FAILED).
  2. 2
    Scarica il log degli errori: fai clic sulla scheda del job e seleziona Scarica CSV errori oppure richiama GET /api/v1/batch-processing/:id/result.csv. Il foglio risultante contiene ogni riga del CSV di origine arricchita con una colonna status (SUCCESS, SKIPPED o FAILED) e una colonna errorMessage che spiega la causa dell'errore (ad esempio: "Proprietà personalizzata obbligatoria mancante: firstName", "Formato data ISO 8601 non valido" o "externalId duplicato").
  3. 3
    Ispeziona i dettagli del job via API: chiama GET /api/v1/batch-processing/:id con la tua chiave API. La risposta JSON restituisce il request payload completo di totalRows, processedRows, successfulRows, failedRows e dell'array errorDetails[] con gli indici esatti delle righe e i codici di errore di validazione.
  4. 4
    Controllo di validazione pre-flight: prima di accodare un job da 100.000 righe, chiama sempre POST /api/v1/batch-processing/:id/validate. Questo passaggio dry-run verifica le mappature delle intestazioni e gli schemi degli attributi senza creare record nel database, segnalando eventuali errori di sintassi prima dell'avvio dei worker.

Perché la mia elaborazione massiva ha creato meno pass rispetto alle righe del file?

Se il tuo CSV di input conteneva 5.000 righe ma il job segnala solo 4.820 pass creati, verifica i seguenti comportamenti previsti dalla piattaforma:

  1. 1
    Deduplicazione tramite External ID (duplicateStrategy): se il modello impone l'univocità dell'External ID e hai impostato duplicateStrategy su SKIP, le righe che condividono un externalId con un pass attivo esistente nel workspace (o già presente in precedenza nello stesso file CSV) vengono saltate per evitare emissioni duplicate. Per sovrascrivere invece i pass esistenti, seleziona duplicateStrategy: "UPSERT_BY_EXTERNAL_ID".
  2. 2
    Righe vuote o finali in bianco: gli editor di fogli di calcolo (Excel, Google Fogli) esportano spesso righe vuote finali contenenti sole virgole. Il parser CSV di Passinstance scarta automaticamente le righe vuote senza incrementare il contatore dei pass generati.
  3. 3
    Rifiuti in fase di pre-validazione degli attributi: le righe con tipi di dati non validi (come testo non numerico in un attributo numerico, sintassi e-mail non valida o stringhe di data non interpretabili) falliscono la validazione a livello di singola riga e vengono registrate nel log degli errori senza interrompere l'intero job.
  4. 4
    Esaurimento della quota di pass attivi (PASS_LIMIT_REACHED): se durante l'elaborazione il workspace raggiunge il 100% del limite di pass attivi previsto dal piano di abbonamento, le righe successive falliscono con PASS_LIMIT_REACHED. Controlla Impostazioni azienda -> Utilizzo e fatturazione per verificare la quota residua.

È normale attendere diverse ore per un'elaborazione massiva?

  • Velocità di elaborazione standard: le code worker dei job in background in Passinstance generano normalmente tra 500 e 2.000 pass al minuto, a seconda che le firme crittografiche dinamiche .pkpass di Apple Wallet e le immagini dei codici a barre vengano generate in modo sincrono oppure differite al momento del download. Un lotto di 10.000 pass si completa di solito in 5–15 minuti.
  • Quando un'attesa di diverse ore è normale:

- Volumi di importazione molto elevati: importazioni estremamente grandi (da 100.000 a oltre 500.000 pass) richiedono diverse ore per mantenere stabili i pool di connessione del database e le code in memoria senza rallentare il workspace. - Invii immediati in uscita: se hai collegato una campagna di consegna E-mail o SMS al job batch, le e-mail in uscita vengono cadenzate in base alle quote di velocità della consegna e-mail gestita (ad es. da 14 a 50 e-mail al secondo) e ai limiti di connessione del server SMTP personalizzato per tutelare la reputazione del tuo dominio.

  • Quando un job è fermo o richiede un intervento:

- Se un job rimane in stato NEW o READY_TO_RUN per ore, significa che il worker non è mai stato avviato. Fai clic su Avvia job nella Dashboard oppure chiama POST /api/v1/batch-processing/:id/start. - Se lo stato del job è PAUSED, riprendi l'esecuzione tramite POST /api/v1/batch-processing/:id/resume.

Un pass può scadere dopo un numero fisso di giorni dall'emissione?

Sì. Passinstance supporta sia la scadenza a data fissa di calendario sia periodi di validità dinamici scorrevoli:

  1. 1
    Durata dinamica scorrevole (validityInDays): nell'Editor visuale, nella sezione Validità e scadenza, imposta la strategia di scadenza su Durata dinamica e indica il numero di giorni (ad es. 30, 90 o 365). Alla creazione di ciascun pass tramite importazione CSV, API o modulo PassFlow, Passinstance calcola automaticamente:

expirationDate = issuanceTimestamp + (validityInDays * 86400 seconds).

  1. 2
    Sovrascrittura della scadenza per singola riga: se singoli clienti hanno date di fine contratto diverse, mappa una colonna CSV contenente timestamp ISO 8601 (ad es. 2027-06-30T23:59:59Z) direttamente sul campo di sistema expirationDate nella fase Mappa campi.
  2. 3
    Proroga post-emissione: puoi estendere o modificare le date di scadenza su migliaia di pass attivi in qualsiasi momento mediante le Operazioni in blocco.

Come posso migrare i dati clienti esistenti da un altro provider di wallet o CRM?

Migrare da sistemi legacy (come Airship, PassKit, Braze o un database interno) verso Passinstance è immediato:

  1. 1
    Esporta i record legacy: esporta il database clienti esistente in un file CSV UTF-8 includendo nomi dei soci, recapiti, saldi punti, livelli e numeri di tessera storici.
  2. 2
    Configura il modello di destinazione: crea in Passinstance un modello equivalente, configurando le proprietà personalizzate (ad es. memberId, pointsBalance, tier) e la simbologia del codice a barre (QR, Aztec, Code 128 o PDF417).
  3. 3
    Mappa gli identificatori storici su externalId: mappa il numero di tessera legacy o l'UUID cliente sul campo di sistema externalId di Passinstance. Questo garantisce continuità 1:1 ed evita record duplicati.
  4. 4
    Esegui l'importazione batch CSV: carica il file CSV tramite la procedura guidata in 5 fasi. Imposta la strategia di importazione su UPSERT_BY_EXTERNAL_ID affinché eventuali record già presenti vengano aggiornati senza conflitti.
  5. 5
    Transizione fluida per i titolari: se la tua organizzazione mantiene lo stesso Apple Pass Type Identifier e lo stesso certificato di firma, i clienti riceveranno i pass aggiornati senza dover eliminare le tessere già presenti nel wallet. In alternativa, invia nuovi smart link di download tramite il Delivery Center utilizzando il segnaposto {passDownloadUrl}.

Come posso ripulire i pass al termine di un evento?

Dopo la conclusione di un concerto, una partita sportiva o una campagna stagionale, mantieni ordinato il workspace e libera quota attiva:

  1. 1
    Individua la coorte dell'evento: nella Dashboard, alla voce Pass (/passes), filtra per il modello dell'evento oppure usa il pannello di ricerca avanzata per filtrare expirationDate < today.
  2. 2
    Seleziona tutti i pass corrispondenti: utilizza la casella nella StickySelectionToolbar per selezionare la vista corrente, poi fai clic sul banner per selezionare tutti i pass che soddisfano il filtro in tutte le pagine.
  3. 3
    Esegui l'annullamento / disattivazione in blocco: fai clic su Azioni in blocco -> Disattiva / Annulla (POST /api/v1/batch-pass-operations/deactivate). Questa azione imposta lo stato dei pass su VOIDED, mostra un banner di codice a barre invalidato sulla schermata di blocco e disabilita la convalida allo scanner, preservando al contempo i log storici delle scansioni e i dati di presenza per i report di conformità.
  4. 4
    Eliminazione logica (DELETING -> SOFT): se desideri rimuovere i pass scaduti dell'evento dalla vista attiva della dashboard, seleziona Azioni in blocco -> Elimina. I pass eliminati logicamente non incidono sui limiti di pass attivi del tuo abbonamento e liberano il relativo externalId per usi futuri, rimanendo comunque accessibili nelle esportazioni storiche di audit.

Per operazioni batch dirette su array JSON senza file CSV, consulta Operazioni in blocco. Per distribuire i pass appena importati via e-mail, consulta Consegna via e-mail e SMS.

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.