Skip to content
Guida del Centro assistenzaFase di onboarding 2
3 min di letturaVerificato 2026-11-16

Carte fedeltà e raccolte timbri

Crea tessere timbro digitali con griglia visiva, incremento a ogni scansione e sblocco premi automatico.

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

Selettore «Aggiungi una meccanica pass» (Zoom)

Scegli tra 6 meccaniche integrate: Raccolta bollini, Riscatto bollini, Valore prepagato, Punti e livelli, Convalida giornaliera o Estensione scadenza.

Panoramica

Carte fedeltà e raccolte timbri digitalizzano le tradizionali tessere cartacee ("Prendi 8 caffè, il 9° è gratis") trasformandole in pass Wallet nativi interattivi sullo smartphone. I clienti non smarriscono mai la tessera, il personale applica i timbri in cassa in due secondi con scansione QR ottica e i merchant stimolano il ritorno in negozio tramite notifiche automatiche in schermata di blocco.

Architettura backend ed enum delle meccaniche

Le tessere a timbri digitali combinano immagini strip dinamiche con l'esecuzione deterministica delle regole in Pass Mechanics Engine:

  • Tipo di pass (pass type): storeCard.
  • Modelli demo a catalogo: restaurant-stamp-card e coffee-loyalty.
  • Tipi di meccanica (mechanic type):

- STAMP_CARD_ADD: Incrementa il numero di timbri attivi di defaultChangeValue (tipicamente 1). - STAMP_CARD_DEDUCT: Consente agli operatori di cassa di correggere timbri errati o scalare timbri in caso di riscatti parziali.

  • Configurazione della griglia visiva dei timbri:

- Array StampImage: Associa gli stati visivi individuali per ogni posizione di timbro 0..N (renderizzati sulle immagini strip Apple e sulle immagini modulari Google Wallet). - maximumValue: Numero totale di timbri necessari per completare la scheda (es. 8 o 10). - rewardImageResourceId: Icona personalizzata di trofeo o premio mostrata quando la tessera raggiunge la capienza massima.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
CICLO RACCOLTA TIMBRI E GESTIONE SOGLIA
FASE 01 PIPELINE DI PROGRESSIONE
1
Scansione iniziale (0 timbri)
2
+1 timbro per visita
3
La tessera raggiunge maximumValue (es. 8)
FASE 02A onCap: "noop"
Tessera ferma a 8/8
Azione applicata: NOOP
Invita lo staff a riscattare
FASE 02B onCap: "reset"
Premio erogato
Contatore torna a 0
Nuovo ciclo immediato
FASE 02C Validazione predefinita
Restituisce HTTP 400
"Stamp card is full; claim reward first"

Logica di esecuzione del motore timbri e comportamenti al limite

Quando un operatore di cassa scansiona il pass del cliente, Pass Mechanics Engine valuta le soglie attive:

  1. 1
    Incremento dei timbri: Aggiunge defaultChangeValue (predefinito 1) al saldo corrente del pass:
TEXT
newStamps = clamp(currentStamps + defaultChangeValue, 0, maximumValue)
  1. 2
    Gestione della soglia massima (onCap) e semantica d'azione (scan action / transaction type):

- onCap: "noop": Quando la tessera raggiunge il numero massimo di timbri, il motore restituisce { ok: true, reason: "Card is full", appliedAction: "NOOP" }. La tessera rimane completa affinché lo staff possa verificarla ed erogare il premio. - onCap: "reset": Attiva automaticamente l'evento premio e azzera i timbri a 0: { ok: true, reason: "Card reset" }. - Comportamento predefinito: Restituisce { ok: false, reason: "Stamp card is full" }, indicando allo staff di avviare un flusso separato di riscatto (POST /api/v1/mechanics/redeem oppure POST /api/v1/passes/:id/use con scan action: INCREMENT, DECREMENT, VALIDATE, registrato con transaction type: EARN, REDEEM, ADJUST, SCAN).

  1. 3
    Comportamenti di riscatto premio (rewardClaimBehavior):

- RESET_TO_ZERO: Riporta tutti i timbri a 0 al momento del riscatto da parte dello staff. - START_NEW_CYCLE: Riporta eventuali timbri in eccesso derivanti da acquisti multipli nel ciclo successivo. - KEEP_COMPLETED: Mantiene lo stato visivo completo fino al ritiro del buono premio.

  1. 4
    Correlazione CRM (externalId): Associ l'ID cliente fedeltà a Pass.externalId così che POS, e-commerce e app mobili possano eseguire upsert puliti tramite POST /api/v1/passes/upsert-by-external-id.
Selettore meccaniche modello nella dashboard
Selettore meccaniche modello nella dashboard

Protezioni sulle scansioni giornaliere (VALID_ONCE_PER_DAY)

Per evitare doppie timbrature accidentali o abusi in cassa, associ la regola secondaria VALID_ONCE_PER_DAY:

  • Il motore risolve il fuso orario della sede commerciale tramite resolveCustomerTimeZone.
  • Se un operatore scansiona due volte la stessa tessera nello stesso giorno solare, la seconda scansione restituisce un avviso informativo (ALREADY_SCANNED_TODAY) senza aggiungere un secondo timbro non autorizzato.

Aggiornamenti in tempo reale nella schermata di blocco

Ogni volta che viene aggiunto o riscattato un timbro:

  • Passinstance invia una notifica silenziosa APNs all'iPhone del cliente.
  • Apple Wallet aggiorna l'immagine strip dei timbri e visualizza un avviso nella schermata di blocco: "You earned a stamp! You now have 5 of 8 stamps."
  • Google Wallet aggiorna il widget live della tessera e mostra una notifica su Android.

Importante: Le immagini strip dinamiche delle carte a timbri vengono generate automaticamente a risoluzioni retina (@1x, @2x, @3x) dal motore grafico di Passinstance, garantendo simboli nitidi su display ad alta densità.

Legga la nostra guida completa Carte a timbri digitali, esplori Ristoranti e caffetterie o consulti la Guida alle regole di raccolta timbri.

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.