Panoramica
Passinstance è una piattaforma di infrastruttura per pass Wallet digitali di livello enterprise, progettata per aziende, sviluppatori e sistemi aziendali. Offre strumenti completi end-to-end per progettare, firmare crittograficamente, distribuire, aggiornare dinamicamente e convalidare pass digitali nativi in Apple Wallet (iOS e watchOS) e Google Wallet (Android) senza richiedere ai clienti di scaricare o gestire un'app mobile personalizzata.
Ogni pass risiede nativamente nello stack Wallet del sistema operativo. Gli utenti finali aggiungono la propria tessera con un solo tocco da un link web, un'e-mail, un SMS o un codice QR. Una volta installati, i pass mostrano codici a barre in tempo reale o credenziali NFC contactless, ricevono notifiche push istantanee quando cambiano saldi o stati e mostrano automaticamente informazioni pertinenti in schermata di blocco in prossimità delle sedi fisiche.
Architettura della piattaforma e stack tecnologico
La piattaforma Passinstance si basa su un'architettura backend modulare NestJS ad alta concorrenza, con code di job asincroni e connettori verso i provider Wallet cloud:
Componenti principali del backend
-
1
API Gateway e moduli di dominio: Costruito con NestJS, organizza le funzionalità in moduli di dominio tra cui
Template subsystem,Pass subsystem,Pass mechanics subsystem,Scanner subsystem,Onboarding subsystemeCertificate subsystem. -
2
Passinstance data layer e database: Applica un rigoroso isolamento tramite chiavi esterne e attributi structured JSON indicizzati tramite indici GIN di database per interrogazioni su campi dinamici.
-
3
Pipeline background job queue e in-memory cache: Gestisce operazioni batch asincrone ad alto volume, inclusi job di generazione pass da CSV, invii e-mail di massa tramite managed email delivery e trasmissioni pianificate di notifiche push.
-
4
Motore di firma crittografica: Impacchetta i bundle Apple
.pkpasscon firme PKCS#7 detached rispetto ai certificati ufficiali Apple WWDR G4/G6 e genera token JWT firmati per gli oggetti Google Wallet.
Importante: Tutti i dati dei clienti, i modelli e le chiavi crittografiche di firma sono ospitati in AWS Europa (Francoforte,
eu-central-1), nel pieno rispetto del GDPR e delle rigorose policy di isolamento multi-tenant.
Due modalità operative per i team su Passinstance
In base alle esigenze tecniche, Passinstance offre sia una suite operativa completa no-code sia una piattaforma per sviluppatori conforme a OpenAPI:
| Modalità operativa | Pubblico di riferimento | Funzionalità principali ed endpoint di supporto |
|---|---|---|
| Dashboard No-Code | Team marketing, operatori retail, club soci, organizzatori di eventi | Editor visuale drag-and-drop per modelli, emissione CSV di massa (POST /api/v1/batch-processing), campagne nel Centro consegne, abbinamento scanner web e mobile. |
| API REST per sviluppatori | Ingegneri del software, sistemi POS, piattaforme CRM ed e-commerce | Ciclo di vita programmatico completo dei pass (/api/v1/passes), verifica scansioni in tempo reale (/api/v1/scans), webhook push/pull dual-mode HMAC-SHA256, chiavi API con scope (pi_live_, pi_test_). |
Programmi pass e tipologie di catalogo supportati
Passinstance supporta nativamente tutti i principali formati di pass Wallet digitali definiti da Apple e Google attraverso l'enum backend pass type:
-
Carte fedeltà e raccolte timbri (
storeCard): Tessere a timbri visive (STAMP_CARD_ADD,STAMP_CARD_DEDUCT) e programmi a punti continui basati sulla spesa (LOYALTY_PROGRAM). -
Tessere socio e abbonamenti (
membership/generic/posterGeneric): Credenziali digitali con estensione automatica della scadenza (RENEW_EXPIRATION), miniature fotografiche, stile poster WWDC (posterGeneric) e restrizioni di condivisione tramite AirDrop. -
Coupon e buoni sconto (
coupon): Pass promozionali monouso protetti daVOIDED_AFTER_SCAN scan modeoINVALIDATE_AFTER_SCANper prevenire il riutilizzo di screenshot. -
Gift card e carte prepagate (
storeCard): Conti a valore memorizzato (PREPAID_CARD) supportati da un registro contabile a partita doppia in unità monetarie minime. -
Biglietti eventi e carte d'imbarco (
eventTicket/boardingPass): Credenziali evento live con campi varco/posto, layout poster WWDC25 (theme preference), guide della sede con MapKit e regole di check-in ai tornelli, oppure titoli di viaggio (transit type: Air, Boat, Bus, Train, Generic). -
Badge dipendenti, tessere studenti e biglietti da visita digitali (
studentId/businessCard/generic): Badge identificativi e biglietti da visita interattivi con trasmissione NFC contactless (Apple VAS e Google Smart Tap) e revoca istantanea.
Funzionalità chiave tra backend e frontend
| Funzionalità | Implementazione backend (Passinstance API) | Esperienza frontend (Passinstance Dashboard / scanner) | |
|---|---|---|---|
Correlazione con sistemi esterni (externalId) | Chiave opzionale univoca per tenant (externalId, max 255 caratteri) indicizzata per pass attivi (archivedAt IS NULL), a supporto della sincronizzazione CRM idempotente via POST /api/v1/passes/upsert-by-external-id. | Ricercabile nei filtri dell'elenco /passes, nella mappatura CSV di massa (Bulk Pass Wizard) e in Pass Details panel. | |
Emissione idempotente (idempotencyKey) | Header HTTP Idempotency-Key (<=128 caratteri [A-Za-z0-9._:-]+) archiviato con verifica del payload tramite hash SHA-256 per evitare creazioni duplicate nei retry di rete. | Generato automaticamente da wizard e SDK retry-safe; ispezionabile nei log API del pass. | |
Bundle multi-carta (bundleId) | Pass.bundleId (bundleId) collega fino a 10 pass associati in un archivio .pkpasses di Apple Wallet tramite pass bundle (bundle grouping mode: AUTO \ | MANUAL). | Gestito tramite PassProject (Wallet Experiences -> scheda Bundle) o selezione batch in /bundles/:id. |
| Meccaniche pass e Scanner | mechanic type, ScanMode, StoredValueOperation e nonce protetti da replay su POST /api/v1/scans. | Validazione operatore tramite Web Scanner (/scanner), app mobile Passinstance Scanner (iOS/Android/Expo con coda offline) o POS esterno (/v1/pos/redeem). |
Misurazione della capacità e vincoli di hosting
Passinstance misura la capacità del piano in base ai Pass Wallet attivi (il conteggio dei pass attualmente installati sui dispositivi dei clienti e collegati agli endpoint push APNs o Google Wallet). Bozze, pass eliminati e link di download non installati non consumano quota attiva dell'abbonamento.
Consulti la nostra Panoramica della piattaforma e approfondisca Meccaniche pass e funzionalità.
