Panoramica
Man mano che la tua organizzazione cresce attraverso campagne stagionali, filiali regionali e ambienti di staging e produzione, Passinstance mette a disposizione strumenti di organizzazione del workspace su più livelli: Categorizzazione e tag dei modelli, Clonazione modelli (Template Duplication Wizard), Filtraggio ciclo di vita rowKind (DRAFT, PUBLISHED, PRODUCTION, ARCHIVED), Applicazione dell'univocità composita degli External ID, Ricerca su attributi con indice GIN su database (attribute search index) e Mappatura dei modelli tra progetti.
Architettura di sistema: tassonomia del workspace, clonazione e viste salvate
1. Copiare un modello esistente (clonazione e duplicazione dei modelli)
Anziché riconfigurare da zero colori, layout dei campi, codici a barre e schemi di proprietà personalizzate per ogni nuovo programma carte, puoi duplicare qualsiasi modello esistente in pochi secondi.
Come clonare dalla Dashboard
Gli operatori possono avviare la clonazione di un modello da due punti:
-
1
Dalla directory Modelli: su qualsiasi scheda modello, fai clic sul menu Tre puntini (...) e seleziona Duplica.
-
2
Dall'Editor visuale: nella CommandBar superiore, fai clic su Azioni -> Duplica modello.
Il flusso in 4 passaggi del Template Duplication Wizard
Il Template Duplication Wizard guida gli operatori nella duplicazione di un modello:
-
1
Passaggio 1: Seleziona modello di origine: conferma il modello sorgente e ne ispeziona tipo di pass, numero di campi e immagini allegate.
-
2
Passaggio 2: Nome e descrizione: precompila il nome del nuovo modello con
${sourceTemplate.name} (Copy)e consente di inserire una descrizione distinta. -
3
Passaggio 3: Personalizzazione:
- Pagina di registrazione PassFlow collegata: scegli se clonare il modulo di registrazione pubblico associato tramite duplicatePassFlow (creando una pagina PassFlow indipendente /f/:newUrl) oppure lasciare il nuovo modello senza modulo collegato. - Colori del brand: modifica backgroundColor, foregroundColor e labelColor. La procedura guidata esegue in tempo reale il controllo del contrasto WCAG AA per garantire la leggibilità. - Asset visivi: scegli se mantenere le immagini del modello sorgente (icon, logo, strip, thumbnail) o caricare nuovi asset grafici del brand.
-
4
Passaggio 4: Assegnazione certificato: seleziona un certificato di firma Apple Pass Type ID esistente dalle impostazioni del workspace oppure carica un nuovo certificato
.p12/.cer.
2. Isolamento del workspace e igiene nella denominazione dei modelli
Passinstance isola modelli, pass, certificati e chiavi API al confine del workspace Customer all'interno della Organization padre (POST /api/v1/organizations/current/workspaces):
-
1
Separa gli ambienti per workspace: mantieni bozze sperimentali e test di integrazione in un workspace
sandbox, riservando il workspaceproductionesclusivamente ai programmi clienti attivi. -
2
Standardizza nomi e tag dei modelli: includi dominio del programma, area geografica e versione nei titoli dei modelli (ad esempio
Loyalty-CoffeeClub-EU-v2) e applicatagsstrutturati (ad es.["retail", "q4-2026", "dach"]) per un filtraggio immediato del catalogo. -
3
Archivia i modelli superati (
rowKind: ARCHIVED): invece di eliminare modelli promozionali storici che hanno ancora pass emessi associati, spostali in stato Archiviato. I modelli archiviati restano nascosti nei selettori attivi predefiniti, ma conservano le analisi storiche e i log delle scansioni nel filtro Tutti / Archiviati.
3. Univocità degli External ID, identificatori personalizzati e raggruppamento in bundle
Per evitare l'emissione di pass duplicati tra moduli web, terminali POS e webhook CRM, configura i criteri di identificazione e bundling nelle Impostazioni del modello:
| Impostazione / Proprietà del modello | Applicazione su database e API | |
|---|---|---|
externalId (Pass.externalId) | Stringa fornita dal chiamante (max 255 caratteri) indicizzata in modo univoco per ogni pass attivo non eliminato del tenant (@@unique([customerId, externalId]) WHERE archivedAt IS NULL). Chiamate duplicate a POST /api/v1/passes vengono rifiutate, mentre POST /api/v1/passes/upsert-by-external-id aggiorna sul posto. | |
Regole identificatori personalizzati (Template) | Configura customIdentifiersEnabled, externalIdentifierPattern e customIdentifierValidationPattern nelle Impostazioni del modello per applicare pattern regex a livello aziendale sugli identificatori esterni generati o importati. | |
Raggruppamento multi-tessera (Pass.bundleId) | Chiave esterna bundleId che collega fino a 10 pass in un unico pass bundle (bundle grouping mode: AUTO \ | MANUAL) per la distribuzione .pkpasses. |
Associazione a un solo dispositivo (limitToOneActivePerPass) | Limita gli smart link di download affinché un singolo pass non possa essere condiviso e installato simultaneamente su dispositivi non autorizzati. |
Importante: L'applicazione dell'univocità su
externalIdè vivamente consigliata per modelli di carte fedeltà, tessere socio e gift card prepagate. L'eliminazione logica di un pass di test (eliminazioneSOFT) impostaarchivedAte libera immediatamente quell'externalIdper il riutilizzo.
4. Indicizzazione strutturata degli attributi JSON (attribute search index) e viste salvate
Ogni proprietà personalizzata archiviata in Pass.attributes viene indicizzata automaticamente tramite l'indice invertito generalizzato del database (attribute search index). Ciò consente a operatori e client API di organizzare e interrogare milioni di pass senza migrazioni di schema:
-
Viste salvate per gli operatori: nella directory Pass (
/passes), combina predicati di filtro AND/OR sustatus(stato del pass),lifecycleStatus,walletVoidStatus(WalletPropagationStatus),bundleId,externalId, piattaforma del dispositivo (APPLE_WALLETvsGOOGLE_WALLET) e chiavi JSON strutturate personalizzate (attributes.tier,attributes.storeId), quindi salva la query come Vista salvata. -
Mappatura dei modelli tra progetti: raggruppa modelli correlati in Wallet Experiences (
PassProject) anziché clonare modelli isolati. Uno stesso modello può ricoprire il ruoloLINKED,VIP,CUSTOMoPRIVACY_MODEall'interno di più contenitoriPassProject(PassProjectTemplateRole), mantenendo una governance centralizzata di asset e meccaniche.
Riferimento API: duplicazione e filtraggio dei modelli
1. Duplicare un modello via API (POST /api/v1/templates/:id/duplicate)
Clona un modello esistente copiando campi di layout, colori, codici a barre e definizioni delle proprietà personalizzate:
POST /api/v1/templates/tmpl_01hxyz987654321/duplicate Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Artisan Coffee Club - Platinum Tier (Copy)",
"duplicatePassFlow": true,
"certificateId": "cert_01j7k8m9n2p3"
}
Risposta HTTP (201 Created)
{
"success": true,
"data": {
"id": "tmpl_new_clone_01h987",
"name": "Artisan Coffee Club - Platinum Tier (Copy)",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"rowKind": "PRODUCTION",
"createdAt": "2026-11-16T21:20:00.000Z"
},
"statusCode": 201
}
2. Filtrare i modelli per stato, tipo e tag
/api/v1/templates?rowKind=PRODUCTION&kind=storeCard&tag=retail&search=Coffee&page=1&limit=20
{
"success": true,
"data": {
"items": [
{
"id": "tmpl_01hxyz987654321",
"groupId": "grp_01hxyz987654321",
"name": "Loyalty-CoffeeClub-EU-v2",
"kind": "storeCard",
"rowKind": "PRODUCTION",
"status": "PUBLISHED",
"versionNumber": 2,
"tags": ["retail", "q4-2026", "dach"],
"activePassesCount": 14820
}
],
"total": 1,
"page": 1,
"limit": 20
},
"statusCode": 200
}
Approfondisci Gestire i progetti per combinare pass provenienti da più modelli oppure leggi Comprendere il proprio workspace per le regole di isolamento multi-workspace.
