Skip to content
Guida del Centro assistenza · Riscatti e transazioniFase di onboarding 2
4 min di letturaVerificato 2026-11-16

Punti fedeltà e timbri

Assegna timbri alla scansione, gestisci il reset premio automatico, accredita punti visita e soglie livello.

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

Passinstance elabora la timbratura delle tessere a timbri, l'accumulo di punti fedeltà, le promozioni automatiche di livello e il riscatto premi tramite Loyalty & Stamp Engine, Pass Mechanics API e Tier Progression Engine. Lo staff e le integrazioni backend possono attivare gli aggiornamenti fedeltà tramite una scansione standard al banco (POST /api/v1/scans), l'esecuzione diretta su pass da scanner (POST /api/v1/scans/pass/:passId/use), l'utilizzo pass autenticato da workspace (POST /api/v1/passes/:id/use), il riscatto da terminale POS (POST /v1/pos/redeem) oppure il riscatto esplicito del premio (POST /api/v1/mechanics/redeem).

Importante: Tutte le variazioni di saldo fedeltà e i riscatti premio vengono eseguiti in transazioni atomiche con rigorosa applicazione dell'idempotenza (header Idempotency-Key o campo idempotencyKey). Dopo qualsiasi modifica di timbri, punti o livello, Passinstance rigenera automaticamente la grafica strip dinamica e invia aggiornamenti push silenziosi ad Apple Wallet e Google Wallet.

Architettura e flusso di esecuzione delle meccaniche

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
ACCUMULO FEDELTÀ, PASSAGGIO DI LIVELLO E RISCATTO PREMIO
ATTORI DI SISTEMA COINVOLTI
P1 Scanner / Terminale POS
P2 Loyalty & Stamp Engine / Mechanics
P3 Tier Progression Engine e Push Wallet
FASE 1 RICHIESTA / AZIONE POST/api/v1/scans
FASE 2 RICHIESTA / AZIONE Esegue ScanAction / Meccanica:
›
{ action: "INCREMENT" }
›
INCREMENT / DECREMENT
›
CREDIT / DEBIT / SET
›
STAMP_CARD / LOYALTY_PROGRAM
FASE 3 RICHIESTA / AZIONE Controlla soglie livello
FASE 4 RICHIESTA / AZIONE Idrata asset/colori livello
FASE 5 RISPOSTA Persiste saldo e ledger
FASE 6 RISPOSTA 200 OK (resultingValue)
FASE 7 RICHIESTA / AZIONE Emette eventi POINTS_UPDATED /
›
8. Push APNs e Google Wallet
›
TIER_CHANGED
›
(Strip e badge aggiornati)

Azioni consentite sulle meccaniche ed endpoint di stato

request payload accetta una di sette azioni esplicite (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET), coerenti con la tassonomia di mastro scan action (INCREMENT | DECREMENT | VALIDATE | DEBIT | CREDIT | NOOP):

EndpointAutenticazione / GuardScopo principale
POST /api/v1/scans/pass/:passId/usex-scanner-keyVariazione di timbri, punti o saldo avviata dallo scanner tramite request payload.
POST /api/v1/passes/:id/useJWT Workspace / Chiave APIEsecuzione di timbri o punti su un pass avviata dal CRM/webhook backend.
POST /api/v1/mechanics/redeemScanner Key o JWT (request payload)Esegue il riscatto completo di timbri o premio (action: 'DECREMENT').
GET /api/v1/mechanics/:mechanicId/passes/:passId/stateScanner Key o JWTRestituisce il saldo attuale di timbri/punti insieme ai flag di capacità allowedActions.
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledgerScanner Key o JWTElenca lo storico delle transazioni della meccanica (?limit=50, max 500).
GET /api/v1/balance-changesJWT Workspace / Chiave APIInterroga lo storico delle variazioni di saldo fedeltà e prepagato sull'intero tenant.

Endpoint per accumulo fedeltà e riscatto premi

1. Esecuzione diretta della meccanica (POST /api/v1/scans/pass/:passId/use)

Dopo che uno scanner o terminale POS ha interrogato il pass (GET /api/v1/scans/pass?barcode=...), può eseguire l'aggiunta di un timbro, l'accredito punti o un decremento direttamente sull'UUID :passId utilizzando request payload:

POST /api/v1/scans/pass/pass_loy_884120/use
Header
x-scanner-key sk_live_cafe_counter_01
Idempotency-Key 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Content-Type application/json
JSON
{
  "action": "INCREMENT",
  "mechanicId": "11111111-2222-4333-8444-555555555555",
  "amount": "2",
  "deviceId": "ios-idfv-cafe-03",
  "operatorId": "barista_03",
  "location": "Main Counter"
}
Campo (request payload)TipoValidazione / Note
actionenum (opzionale, predefinito INCREMENT)Uno tra 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'.
mechanicIdUUID (opzionale)Verifica la meccanica di destinazione associata a questo pass.
amountstringa decimale (opzionale)Deve corrispondere a /^\d+(\.\d{1,6})?$/ (es. "2" o "12.90").
deviceId / operatorId / locationstringhe (opzionali)Registrati sul mastro di audit per la riconciliazione di turno.
idempotencyKeystringa (opzionale)Deve corrispondere all'header Idempotency-Key se entrambi sono forniti.

Risposta (200 OK — IPassUseResponse):

JSON
{
  "success": true,
  "data": {
    "scanId": "scan_01hxyz8820ab",
    "passId": "pass_loy_884120",
    "action": "INCREMENT",
    "success": true,
    "resultingValue": "8"
  },
  "description": "Pass INCREMENT successfully",
  "errors": [],
  "statusCode": 200
}

2. Riscatto di un premio sbloccato (POST /api/v1/mechanics/redeem)

Quando un cliente richiede un premio maturato su una tessera a timbri o spende unità accumulate, invochi POST /api/v1/mechanics/redeem con request payload:

POST /api/v1/mechanics/redeem Header: x-scanner-key: sk_live_cafe_counter_01 (oppure Authorization: Bearer <jwt>) Idempotency-Key: 4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872 Content-Type: application/json

JSON
{
  "passId": "a1b2c3d4-e5f6-4a7b-8c9d-0123456789ab",
  "mechanicId": "11111111-2222-4333-8444-555555555555",
  "ruleId": "default",
  "idempotencyKey": "4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872"
}

(Nota: sia passId sia mechanicId — e l'eventuale idempotencyKey nel corpo JSON — devono essere UUID validi; se fornito, ruleId deve essere uguale a "default".)

Risposta (200 OK — IRedeemResponse):

JSON
{
  "success": true,
  "newBalance": 0,
  "newBalanceDecimal": "0",
  "reward": "default",
  "message": "Reward redeemed successfully"
}

Promozioni automatiche di livello (Tier Progression Engine)

Ogni volta che una scansione, POST /api/v1/scans/pass/:passId/use oppure POST /v1/pos/redeem (operation: "ADD_POINTS" o "ADD_STAMPS") modifica il saldo punti o visite di un pass, Tier Progression Engine valuta le soglie di livello configurate sul modello:

  1. 1
    Valutazione della soglia: Verifica se il saldo aggiornato supera la soglia di un livello superiore (es. Bronze: 0–249, Silver: 250–499, Gold: 500+).
  2. 2
    Idratazione visiva e degli asset: Sostituisce colori di sfondo, immagini strip/banner ed etichette di livello specifiche della fascia sul record del pass.
  3. 3
    Notifica celebrativa in schermata di blocco: Attiva una notifica changeMessage su Apple Wallet (ad es. "Congratulations! You reached Gold Tier") ed emette il trigger di workflow TIER_CHANGED per automatizzare vantaggi di benvenuto bonus.

Scopra di più sulla configurazione dei programmi fedeltà in Carte fedeltà e tessere a timbri e sull'automazione dei premi di livello in Configurazione dei workflow.

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.