Skip to content
Helpcentrum-gids · Inwisseling & transactiesOnboardingfase 2
3 min leestijdGecontroleerd 2026-11-16

Spaarpunten & stempels

Ken stempels toe bij scan, reset volle kaarten automatisch, reken bezoekpunten bij en verwerk niveau-upgrades.

In deze gids

Interactieve UI-weergaven

Openen in onboardinggids (6 fasen)

Bekijk de exacte dashboardpanelen, knoppen en ingezoomde toelichtingen bij deze gids.

Ingezoomde UI-focus
Belangrijke UI-onderdelen

Kiezer 'Add a Pass Mechanic' (Ingesneden)

Kies uit 6 ingebouwde mechanieken: Stempelkaart, Stempelverzilvering, Tegoed (Stored Value), Punten & niveaus, Validatie eenmaal per dag of Vervaldatum verlengen.

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 veld idempotencyKey). 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

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
LOYALITEITSOPBOUW, TIER-UPGRADE & BELONINGSINWISSELING
DEELNEMENDE SYSTEEMACTOREN
P1 Scanner / POS-terminal
P2 Loyalty & Stamp Engine / Mechanics
P3 Tier Progression Engine & Wallet Push
STAP 1 VERZOEK / ACTIE POST/api/v1/scans
STAP 2 VERZOEK / ACTIE Voer ScanAction / Mechanic uit:
›
{ action: "INCREMENT" }
›
INCREMENT / DECREMENT
›
CREDIT / DEBIT / SET
›
STAMP_CARD / LOYALTY_PROGRAM
STAP 3 VERZOEK / ACTIE Controleer tierdrempels
STAP 4 VERZOEK / ACTIE Hydrateer tierassets
STAP 5 ANTWOORD Sla saldo & grootboek op
STAP 6 ANTWOORD 200 OK (resultingValue)
STAP 7 VERZOEK / ACTIE Zend POINTS_UPDATED /
›
8. APNs & Google Push
›
TIER_CHANGED-events uit
›
(Nieuwe strip & tierbadge)

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):

EndpointAuthenticatie / GuardHoofddoel
POST /api/v1/scans/pass/:passId/usex-scanner-keyDoor scanner geïnitieerde stempel-, punten- of saldomutatie via request payload.
POST /api/v1/passes/:id/useWerkruimte-JWT / API KeyDoor backend-CRM/webhook geïnitieerde uitvoering van stempels of punten op een pas.
POST /api/v1/mechanics/redeemScanner Key of JWT (request payload)Voert een stempel- of beloningsinwisseling voor een volle kaart uit (action: 'DECREMENT').
GET /api/v1/mechanics/:mechanicId/passes/:passId/stateScanner Key of JWTRetourneert het huidige stempel-/puntensaldo plus allowedActions-capaciteitsvlaggen.
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledgerScanner Key of JWTGeeft historische mechanicatransacties weer (?limit=50, max. 500).
GET /api/v1/balance-changesWerkruimte-JWT / API KeyBevraagt 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:

POST /api/v1/scans/pass/pass_loy_884120/use
Headers
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"
}
Veld (request payload)TypeValidatie / opmerkingen
actionenum (optioneel, standaard INCREMENT)Een van 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'.
mechanicIdUUID (optioneel)Verifieert de doelmechanica gekoppeld aan deze pas.
amountdecimale string (optioneel)Moet overeenkomen met /^\d+(\.\d{1,6})?$/ (bijv. "2" of "12.90").
deviceId / operatorId / locationstrings (optioneel)Vastgelegd in het auditgrootboek voor dienstenafstemming.
idempotencyKeystring (optioneel)Moet overeenkomen met de Idempotency-Key-header als beide worden verstrekt.

Antwoord (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. 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

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):

JSON
{
  "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. 1
    Drempelevaluatie: controleert of het bijgewerkte saldo een hogere tier bereikt (bijv. Bronze: 0–249, Silver: 250–499, Gold: 500+).
  2. 2
    Hydratatie van visuals & assets: vervangt tierspecifieke achtergrondkleuren, strip-/bannerafbeeldingen en tierlabelvelden op het pasrecord.
  3. 3
    Felicitatiemelding op vergrendelscherm: activeert een Apple Wallet changeMessage-melding (bijv. "Congratulations! You reached Gold Tier") en verzendt de workflowtrigger TIER_CHANGED zodat u welkomstbonussen kunt automatiseren.

Lees meer over het configureren van loyaliteitsprogramma's in Spaar- & stempelkaarten en het automatiseren van tierbeloningen in Workflowconfiguratie.

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.