Skip to content
Guida del Centro assistenza
3 min di letturaVerificato 2026-11-16

Tessere socio e abbonamenti

Sostituisci le tessere fisiche di club, palestre e associazioni con date di rinnovo sempre aggiornate.

In questa guida

Panoramica

Centri fitness, associazioni sportive, circoli privati, spazi di coworking ed enti non-profit sostituiscono le costose tessere in plastica con pass digitali live in Apple Wallet e Google Wallet. Le tessere riflettono il livello attivo dell'abbonamento, aggiornano automaticamente la data di rinnovo al pagamento e applicano la validazione giornaliera agli ingressi in reception.

Architettura backend e tipi di pass

Nel backend di Passinstance, le credenziali di abbonamento utilizzano layout dedicati alle tessere socio:

  • Tipo di pass (pass type): membership oppure generic (mostra le credenziali del socio con badge di livello evidenti e data di scadenza nell'intestazione).
  • Modelli demo a catalogo: gym-membership e hotel-membership.
  • Tipo di meccanica (mechanic type): RENEW_EXPIRATION.
  • Schema principale della tessera socio:

- primaryFields: Nome completo del socio ({fullName}). - secondaryFields: Livello abbonamento ({membershipTier}) e Stato ({status}). - auxiliaryFields: Numero tessera ({memberNumber}) e Socio dal ({memberSince}). - headerFields: Data di scadenza ({expirationDate}) in formato ISO 8601 con formattazione localizzata.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
CICLO DI RINNOVO ABBONAMENTO
ATTORI DI SISTEMA COINVOLTI
P1 Webhook Stripe / CRM
P2 Passinstance Core API
P3 Database Passinstance database
P4 Wallet dispositivo socio
FASE CTX CONTESTO customer.subscription.updated
FASE 1 RICHIESTA / AZIONE POST/api/v1/passes/upsert-by-external-id
FASE 2 RICHIESTA / AZIONE Estendi validità
›
expirationDate: "2027-12-31 23:59")
›
(Aggiorna record
›
e rimuovi sospensioni)
FASE 3 RICHIESTA / AZIONE Push silenziosa APNs
FASE 4 RISPOSTA 200 OK ({ data: { pass, action } })
›
& Google REST PATCH | (Avviso lock-screen
›
"Membership renewed")

Estensione automatica della scadenza e sincronizzazione dei rinnovi

Passinstance mette a disposizione due flussi distinti di rinnovo:

1. Integrazione con CRM e fatturazione guidata da webhook

Quando un socio rinnova un abbonamento ricorrente tramite Stripe, Recurly o software di fatturazione personalizzato:

  • Il sistema di fatturazione esterno invia una richiesta idempotente a POST /api/v1/passes/upsert-by-external-id (oppure PUT /api/v1/passes/by-external-id/:externalId) indicizzata per externalId (vincolo univoco customerId + externalId tra i pass attivi non eliminati).
  • Passinstance crea la tessera (action: "CREATED") se nessun pass attivo corrisponde a externalId, oppure aggiorna attributes, expirationDate e status: "ACTIVE" (action: "UPDATED"), restituendo { success: true, data: { pass, action: "CREATED" | "UPDATED" } }.
  • Una push silenziosa in background aggiorna la tessera in Apple Wallet e Google Wallet, visualizzando un avviso nativo nella schermata di blocco quando i campi definiscono messaggi changeMessage con %@.
  • Per piani famiglia o aziendali, è possibile collegare le tessere dei membri sotto un bundleId condiviso (/api/v1/bundles) o PassProject così da installare tutti i pass insieme.

2. Scadenza guidata dal check-in (RENEW_EXPIRATION)

Per abbonamenti a pacchetto ingressi o estesi a visita:

  • La meccanica RENEW_EXPIRATION aggiunge automaticamente un intervallo configurato (ad esempio +30 days) a expirationDate ogni volta che il pass viene scansionato con successo a un tornello d'ingresso.

Controlli di sicurezza e protezioni anti-condivisione

Per tutelare i ricavi ricorrenti degli abbonamenti, Passinstance applica restrizioni di condivisione a livello di dispositivo:

  • Blocco condivisione AirDrop su Apple Wallet (sharingProhibited: true): Rimuove le icone native di condivisione e AirDrop su iOS, legando la tessera socio esclusivamente all'account iCloud verificato del titolare e ai relativi dispositivi registrati.
  • Modifiche self-service controllate (allowUserEdits: true): Permette ai soci di aggiornare dati personali autorizzati (come numero di telefono o e-mail di contatto) tramite portale web sicuro, mantenendo bloccati i campi critici (expirationDate, membershipTier, memberNumber) dietro permessi amministrativi.
  • Controlli ai varchi della reception (CHECK_IN scan mode): L'app Passinstance Scanner verifica che status === ACTIVE e che il pass non sia scaduto né sospeso per mancato pagamento.

Self-service dei soci ed emissione di massa

  • Acquisizione nuovi soci: Iscriva nuovi soci in autonomia tramite moduli pubblici PassFlow con pagamento integrato con carta di credito o verifica OTP via SMS.
  • Sincronizzazione elenchi soci esistenti: Importi migliaia di soci esistenti in pochi minuti tramite il Worker CSV per operazioni batch (POST /api/v1/batch-processing), senza alcun inserimento manuale.

Importante: Impostare sharingProhibited: true nelle impostazioni del modello impedisce ai soci di palestre e club di inviare via messaggio o AirDrop la propria tessera attiva ad ospiti non paganti.

Approfondisca con Tessere socio, Centri fitness e club e Associazioni non-profit.

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.