Skip to content
Guida del Centro assistenza · Introduzione a Passinstance
5 min di letturaVerificato 2026-11-16

Cos'è Passinstance?

Scopri come Passinstance abilita tessere Apple Wallet e Google Wallet senza richiedere un'app mobile dedicata.

In questa guida

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:

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
ARCHITETTURA DELLA PIATTAFORMA
FASE 01 LIVELLO CLIENT E ACQUISIZIONE
Dashboard Admin
(React / Vite SPA)
Punto vendita e POS
(Mobile / Web / API)
PassFlow pubblico
(Acquisizione self-srv)
FASE 02 BACKEND CORE DI PASSINSTANCE (API)
Motore modulare NestJS (apps/api)
Prefisso globale: /api/v1 e Apple Web Service: /v1
RBAC Guard e scoping multi-tenant (Organization / Customer)
Motore meccaniche (Pass Mechanics Engine, Tier Progression Engine)
Firma crittografica (Apple Wallet Packager PKCS#7 e generatore JWT Google
DB database
Schema Passinstance
Tenancy isolata
in-memory cache e ba
Code
Pipeline worker
round job queue
e APNs | | Risor
Pass Retina
FASE 01 RETI CLOUD WALLET
Apple APNs HTTP/2
Protocollo Gateway
Google Wallet
Cloud API REST
FASE 02 DISPOSITIVI CLIENTI
Apple Wallet
(iOS/watchOS)
Google Wallet
(Android)

Componenti principali del backend

  1. 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 subsystem e Certificate subsystem.
  2. 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. 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. 4
    Motore di firma crittografica: Impacchetta i bundle Apple .pkpass con 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à operativaPubblico di riferimentoFunzionalità principali ed endpoint di supporto
Dashboard No-CodeTeam marketing, operatori retail, club soci, organizzatori di eventiEditor 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 sviluppatoriIngegneri del software, sistemi POS, piattaforme CRM ed e-commerceCiclo 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 da VOIDED_AFTER_SCAN scan mode o INVALIDATE_AFTER_SCAN per 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 Scannermechanic 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à.

Documentazione prodotto e API correlata

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.