Overzicht
Passinstance verwerkt stempelkaartmutaties, opbouw van spaarpunten, automatische tierpromoties en beloningsinwisselingen via Loyalty & Stamp Engine, Pass Mechanics API en Tier Progression Engine. Medewerkers en backendintegraties kunnen loyaliteitsupdates activeren via een standaard baliescan (POST /api/v1/scans), directe pasuitvoering vanaf een scanner (POST /api/v1/scans/pass/:passId/use), werkruimte-geauthenticeerd pasgebruik (POST /api/v1/passes/:id/use), POS-terminalinwisseling (POST /v1/pos/redeem) of expliciete beloningsinwisseling (POST /api/v1/mechanics/redeem).
Belangrijk: Alle loyaliteitssaldomutaties en beloningsinwisselingen worden uitgevoerd in atomaire transacties met strikte handhaving van idempotency (
Idempotency-Key-header of het veldidempotencyKey). Na elke stempel-, punten- of tierwijziging genereert Passinstance automatisch dynamische stripafbeeldingen opnieuw en verzendt het stille pushupdates naar Apple Wallet en Google Wallet.
Architectuur & uitvoeringsstroom van mechanica
Toegestane mechanica-acties & status-endpoints
request payload accepteert een van zeven expliciete acties (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET), overeenkomend met de grootboektaxonomie van scan action (INCREMENT | DECREMENT | VALIDATE | DEBIT | CREDIT | NOOP):
| Endpoint | Authenticatie / Guard | Hoofddoel |
|---|---|---|
POST /api/v1/scans/pass/:passId/use | x-scanner-key | Door scanner geïnitieerde stempel-, punten- of saldomutatie via request payload. |
POST /api/v1/passes/:id/use | Werkruimte-JWT / API Key | Door backend-CRM/webhook geïnitieerde uitvoering van stempels of punten op een pas. |
POST /api/v1/mechanics/redeem | Scanner Key of JWT (request payload) | Voert een stempel- of beloningsinwisseling voor een volle kaart uit (action: 'DECREMENT'). |
GET /api/v1/mechanics/:mechanicId/passes/:passId/state | Scanner Key of JWT | Retourneert het huidige stempel-/puntensaldo plus allowedActions-capaciteitsvlaggen. |
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger | Scanner Key of JWT | Geeft historische mechanicatransacties weer (?limit=50, max. 500). |
GET /api/v1/balance-changes | Werkruimte-JWT / API Key | Bevraagt de tenantbrede mutatiegeschiedenis voor loyaliteits- en prepaidsaldo's. |
Endpoints voor loyaliteitsopbouw & beloningsinwisseling
1. Directe mechanica-uitvoering (POST /api/v1/scans/pass/:passId/use)
Zodra een scanner of POS-terminal de pas heeft opgezocht (GET /api/v1/scans/pass?barcode=...), kan deze rechtstreeks tegen de UUID :passId een stempeltoevoeging, puntentoekenning of afschrijving uitvoeren met 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"
}
Veld (request payload) | Type | Validatie / opmerkingen |
|---|---|---|
action | enum (optioneel, standaard INCREMENT) | Een van 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'. |
mechanicId | UUID (optioneel) | Verifieert de doelmechanica gekoppeld aan deze pas. |
amount | decimale string (optioneel) | Moet overeenkomen met /^\d+(\.\d{1,6})?$/ (bijv. "2" of "12.90"). |
deviceId / operatorId / location | strings (optioneel) | Vastgelegd in het auditgrootboek voor dienstenafstemming. |
idempotencyKey | string (optioneel) | Moet overeenkomen met de Idempotency-Key-header als beide worden verstrekt. |
Antwoord (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. Een vrijgespeelde beloning inwisselen (POST /api/v1/mechanics/redeem)
Wanneer een klant een verdiende stempelkaartbeloning claimt of opgebouwde eenheden besteedt, roept u POST /api/v1/mechanics/redeem aan met request payload:
POST /api/v1/mechanics/redeem Headers: x-scanner-key: sk_live_cafe_counter_01 (of 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"
}
(Opmerking: zowel passId als mechanicId — en het optionele idempotencyKey in de JSON-body — moeten geldige UUID's zijn; indien opgegeven, moet ruleId gelijk zijn aan "default".)
Antwoord (200 OK — IRedeemResponse):
{
"success": true,
"newBalance": 0,
"newBalanceDecimal": "0",
"reward": "default",
"message": "Reward redeemed successfully"
}
Automatische tier-upgrades (Tier Progression Engine)
Telkens wanneer een scan, POST /api/v1/scans/pass/:passId/use of POST /v1/pos/redeem (operation: "ADD_POINTS" of "ADD_STAMPS") het punten- of bezoeksaldo van een pas muteert, evalueert Tier Progression Engine de geconfigureerde tierdrempels van het sjabloon:
-
1
Drempelevaluatie: controleert of het bijgewerkte saldo een hogere tier bereikt (bijv.
Bronze: 0–249,Silver: 250–499,Gold: 500+). -
2
Hydratatie van visuals & assets: vervangt tierspecifieke achtergrondkleuren, strip-/bannerafbeeldingen en tierlabelvelden op het pasrecord.
-
3
Felicitatiemelding op vergrendelscherm: activeert een Apple Wallet
changeMessage-melding (bijv. "Congratulations! You reached Gold Tier") en verzendt de workflowtriggerTIER_CHANGEDzodat u welkomstbonussen kunt automatiseren.
Lees meer over het configureren van loyaliteitsprogramma's in Spaar- & stempelkaarten en het automatiseren van tierbeloningen in Workflowconfiguratie.
