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-Keyo campoidempotencyKey). 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
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):
| Endpoint | Autenticazione / Guard | Scopo principale |
|---|---|---|
POST /api/v1/scans/pass/:passId/use | x-scanner-key | Variazione di timbri, punti o saldo avviata dallo scanner tramite request payload. |
POST /api/v1/passes/:id/use | JWT Workspace / Chiave API | Esecuzione di timbri o punti su un pass avviata dal CRM/webhook backend. |
POST /api/v1/mechanics/redeem | Scanner Key o JWT (request payload) | Esegue il riscatto completo di timbri o premio (action: 'DECREMENT'). |
GET /api/v1/mechanics/:mechanicId/passes/:passId/state | Scanner Key o JWT | Restituisce il saldo attuale di timbri/punti insieme ai flag di capacità allowedActions. |
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger | Scanner Key o JWT | Elenca lo storico delle transazioni della meccanica (?limit=50, max 500). |
GET /api/v1/balance-changes | JWT Workspace / Chiave API | Interroga 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:
/api/v1/scans/pass/pass_loy_884120/use
{
"action": "INCREMENT",
"mechanicId": "11111111-2222-4333-8444-555555555555",
"amount": "2",
"deviceId": "ios-idfv-cafe-03",
"operatorId": "barista_03",
"location": "Main Counter"
}
Campo (request payload) | Tipo | Validazione / Note |
|---|---|---|
action | enum (opzionale, predefinito INCREMENT) | Uno tra 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'. |
mechanicId | UUID (opzionale) | Verifica la meccanica di destinazione associata a questo pass. |
amount | stringa decimale (opzionale) | Deve corrispondere a /^\d+(\.\d{1,6})?$/ (es. "2" o "12.90"). |
deviceId / operatorId / location | stringhe (opzionali) | Registrati sul mastro di audit per la riconciliazione di turno. |
idempotencyKey | stringa (opzionale) | Deve corrispondere all'header Idempotency-Key se entrambi sono forniti. |
Risposta (200 OK — IPassUseResponse):
{
"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
{
"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):
{
"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
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
Idratazione visiva e degli asset: Sostituisce colori di sfondo, immagini strip/banner ed etichette di livello specifiche della fascia sul record del pass.
-
3
Notifica celebrativa in schermata di blocco: Attiva una notifica
changeMessagesu Apple Wallet (ad es. "Congratulations! You reached Gold Tier") ed emette il trigger di workflowTIER_CHANGEDper 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.
