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

Programmi punti e premi

Progetta programmi a livelli Punti e Tier con regole di accumulo, avanzamenti automatici e notifiche.

In questa guida

Panoramica

A differenza delle tessere a timbri a soglia fissa, i Programmi premi e fedeltà modellano un accumulo continuo di punti e una progressione multi-livello (ad esempio Bronzo -> Argento -> Oro -> Platino). Passinstance mette a disposizione un motore fedeltà enterprise con regole dinamiche punti-per-spesa, valutazione automatica dei livelli, API per il riscatto premi e aggiornamenti push Wallet in tempo reale.

Architettura backend e motore fedeltà

I programmi fedeltà combinano il tracciamento continuo del saldo con definizioni strutturate dei livelli nello schema Passinstance database:

  • Tipo di pass (pass type): storeCard (mostra il saldo punti attivo nelle zone principali in evidenza).
  • Modello demo a catalogo: retail-loyalty.
  • Tipo di meccanica (mechanic type): LOYALTY_PROGRAM.
  • Modelli fedeltà principali:

- Tier: Configura le soglie richieste (es. 500 punti per Argento, 1.500 punti per Oro), i vantaggi del livello, i colori visivi personalizzati e le immagini dedicate del badge di livello. - BalanceChange: Registro transazionale immutabile che documenta ogni accredito punti, deduzione per riscatto e rettifica amministrativa.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
ACCUMULO PUNTI E AVANZAMENTO LIVELLO
ATTORI DI SISTEMA COINVOLTI
P1 Acquisto POS / E-Commerce
P2 Passinstance Core API
P3 Tier Progression Engine
P4 Pass Wallet cliente
FASE CTX CONTESTO Acquisto: €120120 Pti
FASE 1 RICHIESTA / AZIONE POST/api/v1/passes/:id/use
›
(oppure /api/v1/scans/pass/:id/use)
FASE 2 RICHIESTA / AZIONE Aggiorna saldo
›
(cur + step clamped)
FASE 3 RICHIESTA / AZIONE Valuta livelli
›
(Soglia superata:
›
ArgentoOro)
FASE 4 RISPOSTA Livello promosso
FASE 5 RICHIESTA / AZIONE Push silenziosa APNs
FASE 6 RISPOSTA 200 OK (Nuovo livello)
›
& PATCH REST Google | (Passa al tema Oro
›
Banner lock-screen:
›
"Upgraded to Gold!")

Motore di accumulo punti e progressione livelli

Pass Mechanics Engine e Tier Progression Engine eseguono le regole fedeltà:

1. Calcolo dell'accumulo

Quando avviene un acquisto o una visita:

  • L'incremento punti utilizza defaultChangeValue come valore canonico, ripiegando su config.pointsPerScan o 1.
  • Per integrazioni POS ed e-commerce, i punti vengono calcolati dinamicamente in base all'importo speso:
TEXT
earnedPoints = floor(purchaseTotal * pointsMultiplier)
  newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
  • Se autoResetAtMaximum: true oppure config.onCap === "reset", il saldo punti viene riportato a resetTargetValue (o al saldo iniziale) al raggiungimento di maximumValue.

2. Avanzamento automatico di livello (Tier Progression Engine)

Dopo ogni variazione del saldo, Tier Progression Engine confronta i punti accumulati dal cliente con le soglie attive dei livelli:

  • Se una soglia viene superata, il servizio promuove il cliente al livello superiore.
  • Aggiorna automaticamente lo stile visivo della tessera (modificando colori di sfondo, etichette d'intestazione e icone badge del livello).
  • Attiva una push silenziosa APNs e un aggiornamento REST Google Wallet, avvisando il cliente con una notifica nativa sulla schermata di blocco: "Congratulations! You have reached Gold Tier."

API per il riscatto dei premi

Quando un cliente riscatta punti per sconti, prodotti omaggio o articoli promozionali in negozio o online:

Richiesta HTTP

POST /api/v1/mechanics/redeem
Header
X-API-Key <API_KEY>
Content-Type application/json
JSON
{
  "passId": "8f94d930-b302-4fc8-9f12-000000000001",
  "mechanicId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
  "idempotencyKey": "redeem_tx_88194"
}

Risposta HTTP (200 OK)

JSON
{
  "success": true,
  "newBalance": 240,
  "newBalanceDecimal": "240",
  "message": "Reward redeemed successfully"
}

Sincronizzazione e-commerce e multicanale

Colleghi casse in negozio e store online per mantenere un registro unificato del cliente (transaction type: EARN, REDEEM, ADJUST, REFUND, TRANSFER, BONUS, PENALTY, SCAN, API, ADJUSTMENT):

  • Connettori Shopware 6 / Shopify: Acquisiscono webhook degli ordini online (/api/v1/automations/webhooks/shopify/:customerId, /api/v1/automations/webhooks/woocommerce/:customerId o webhook del plugin Shopware) e accreditano automaticamente i punti sui pass Wallet associati tramite externalId.
  • API canonica di utilizzo pass (POST /api/v1/passes/:id/use): Endpoint programmatico consigliato per ERP, app e servizi backend per modificare saldi e punti (con controparte autenticata da scanner POST /api/v1/scans/pass/:passId/use). L'acquisizione legacy di eventi meccanica (POST /api/v1/mechanics/:mechanicId/events) rimane supportata per retrocompatibilità, sebbene sia deprecata per nuove integrazioni.

Importante: Configuri changeMessage: "Points balance updated to %@" sul campo principale dei punti nell'editor del modello. Ogni volta che vengono guadagnati o scalati punti, la schermata di blocco del cliente mostra immediatamente il saldo aggiornato.

Approfondisca la nostra Soluzione Fedeltà, esplori Carte fedeltà oppure consulti la Guida alle regole di progressione fedeltà.

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.