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-cardecoffee-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.
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
Incremento dei timbri: Aggiunge
defaultChangeValue(predefinito1) al saldo corrente del pass:
newStamps = clamp(currentStamps + defaultChangeValue, 0, maximumValue)
-
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).
-
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.
-
4
Correlazione CRM (
externalId): Associ l'ID cliente fedeltà aPass.externalIdcosì che POS, e-commerce e app mobili possano eseguire upsert puliti tramitePOST /api/v1/passes/upsert-by-external-id.

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.
