Skip to content
Helpcentrum-gids · Passen scannenOnboardingfase 4
3 min leestijdGecontroleerd 2026-11-16

Scanmodi & validatieregels

Stel eenmalig inwisselen, in-/uitchecken, eenmaal-per-dag-regels, feedbackmeldingen en offline-caching in.

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

Bericht na scannen & Scannerconfiguraties (Ingesneden)

Pas het bevestigingsbericht voor de medewerker aan met variabelen zoals {holderName} en beheer actieve scannertoegangslinks.

Overzicht

Elke scan die naar POST /api/v1/scans wordt verzonden, wordt beoordeeld op basis van de actieve ScannerConfiguration (herleid vanuit de gekoppelde x-scanner-key of scannerConfigurationId / validationConfigId in request payload) en een deterministische Validation Rules Engine-pijplijn met 14 regels. Samen bepalen deze instellingen of een pas een aanwezigheid registreert, na één keer gebruiken ongeldig wordt, de incheckstatus op locatie omschakelt, een tegoed muteert of cryptografische anti-replay-nonces afdwingt.

Dialoogvenster voor aanmaken van scannerconfiguratie
Dialoogvenster voor aanmaken van scannerconfiguratie

Belangrijk: Validatieregels worden atomair uitgevoerd op de server. Wanneer een scan de passtatus muteert (zoals VOIDED_AFTER_SCAN of StoredValueOperation.SUBTRACT), worden gelijktijdige dubbele verzoeken geserialiseerd met behulp van idempotency-vergrendelingen (x-idempotency-key) om race conditions tussen meerdere kassa's te voorkomen.

Configuratie- & uitkomstopnames (Enumerations)

Bij het configureren van validatieprofielen onder Scanner -> Scanner Configurations (/scanner/configs) of via /api/v1/validation/configs bepalen vijf Passinstance database-enumeraties het terminalgedrag en de opgeslagen scanuitkomsten:

1. ScanMode-enum

ScanMode-waardeGedrag & statusovergangTypische toepassing
SAVE_ATTENDANCERegistreert een geldige scangebeurtenis en voert gekoppelde spaar-/stempelmechanica uit zonder de pas ongeldig te maken.Spaarkaarten voor meerdere bezoeken, sportschoolabonnementen, seizoenskaarten.
VOIDED_AFTER_SCANZet de passtatus atomair om naar VOIDED bij de eerste geldige scan; volgende scans retourneren ALREADY_VOIDED.Eenmalige coupons, promotievouchers, eenmalige toegangstickets.
INVALIDATE_AFTER_SCANMarkeert de pas als ongeldig na inwisseling en blokkeert toekomstige acceptatie onder de validatieconfiguratie.Passen voor eenmalige inwisseling en beperkte gastvouchers.
CHECK_INZet de aanwezigheidsstatus van de pas op ingecheckt; weigert herhaalde check-ins als de bezoeker al binnen is.Toegang tot conferentiesessies, gecontroleerde toegangspoorten.
CHECK_OUTZet de aanwezigheidsstatus van de pas om van ingecheckt naar uitgecheckt.Bijhouden van locatiebezetting, capaciteitsbeheer.
CHECK_IN_CHECK_OUT_TOGGLEWisselt automatisch tussen CHECK_IN en CHECK_OUT bij opeenvolgende scans.Co-workingspaces, meerdaagse festivalpolsbandjes/passen.

2. Enumeraties voor opgeslagen tegoed, NFC & scanuitkomsten

Enum-typeToegestane waardenDoel
StoredValueOperationNONE, ADD, SUBTRACT, SETBepaalt of een scan saldo's ongemoeid laat, tegoed opwaardeert (ADD), aankoopwaarde afboekt (SUBTRACT) of het saldo overschrijft (SET).
StoredValueAmountSourceFIXED, OPERATOR, MECHANICBepaalt of het transactiebedrag afkomstig is van een vooraf ingestelde configuratiewaarde (FIXED), invoer van de kassier (OPERATOR) of de sjabloonmechanica (MECHANIC).
NfcReaderModeAUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAPConfigureert protocolonderhandeling voor contactloze lezers voor Apple VAS en Google Smart Tap-terminals.
scan actionINCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOPActie die wordt vastgelegd op elke pasgebruik- of scangrootboektransactie (request payload staat ook SET toe).
scan statusSUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUTGranulaire opgeslagen status die wordt bewaard op het Scan-auditrecord (inclusief expliciete in-/uitcheckovergangen).

De 14-regelige Validation Rules Engine-pijplijn

Wanneer POST /api/v1/scans een payload ontvangt, voert Validation Rules Engine 14 geprioriteerde validatieregels uit verspreid over vier fasen (Core -> Mechanics -> Security -> Fallback):

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
PIJPLIJN MET 14 BEDRIJFSVALIDATIEREGELS
FASE 01 POST/api/v1/scans (request payload + x-scanner-key)
FASE 02 Fase 1: Kernregels
1
PassStatusRuleControleer of pas ACTIVE is (niet VOIDED / SUSPENDED)
2
ExpirationRuleControleer now() < expirationDate
3
TimeWindowRuleControleer of scan binnen toegestane tijdschema valt
4
GeofencingRuleControleer of scanner GPS {lat, lng} binnen radius ligt
FASE 03 Fase 2: Mechanicaregels
5
OncePerDayRuleWeiger als pas al gescand is binnen voortschrijdend venster
6
StampCardAddRuleVerhoog stempelteller & beoordeel mijlpaal
7
StampCardDeductRuleTrek stempels af voor beloningsinwisseling
8
PrepaidCardRuleVoer ADD / SUBTRACT / SET uit op opgeslagen tegoed
9
LoyaltyProgramRuleBereken & pas pointsDelta toe
10
TierEvaluationRuleUpgrade pastier bij overschrijding drempelwaarde
FASE 04 Fase 3: Beveiligingsregels
11
RateLimitRuleVoorkom snelle scanoverstroming op één pas
12
AntiReplayRuleVerifieer cryptografische scan nonce uit /scans/prepare
13
DeviceValidationRuleVerifieer scannersleutel & terminalkoppeling
FASE 05 Fase 4: Terugval
14
DefaultAcceptanceRuleGeef beslissing af: "SUCCESS", status: "ACCEPTED"

Elke regel die tijdens een scan wordt geëvalueerd, voegt zijn uitvoeringsresultaat toe aan de array ruleTrace in request payload, wat een volledig diagnostisch spoor oplevert.

Anti-replay-nonces (POST /api/v1/scans/prepare)

Om waardevolle tickets en vouchers te beschermen tegen statische screenshots van barcodes, kunnen terminals voorafgaand aan de definitieve uitvoering een kortlevende cryptografische scan nonce opvragen:

Verzoek

POST /api/v1/scans/prepare
Header
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "scannedBarcodeValue": "PI-TKT-992014",
  "scannerConfigurationId": "scfg_main_entrance_01"
}

Antwoord (201 Created)

JSON
{
  "success": true,
  "data": {
    "nonce": "snonce_8841a9c2f01e4b72",
    "expiresAt": "2026-11-15T22:35:30.000Z"
  }
}

Door "nonce": "snonce_8841a9c2f01e4b72" mee te sturen in de daaropvolgende POST /api/v1/scans-payload voldoet het verzoek aan AntiReplayRule en wordt de nonce onmiddellijk verbruikt zodat deze niet opnieuw kan worden afgespeeld.

Scanuitvoeringsschema (POST /api/v1/scans)

request payload-payload

JSON
{
  "scannedBarcodeValue": "PI-LOY-449102",
  "scannerConfigurationId": "scfg_register_01",
  "nonce": "snonce_8841a9c2f01e4b72",
  "timestamp": "2026-11-15T22:35:10.000Z",
  "location": {
    "lat": 52.520008,
    "lng": 13.404954
  },
  "channel": "NFC",
  "protocol": "VAS",
  "validationData": {
    "amount": 18.50,
    "place": "Flagship Berlin Store"
  },
  "operatorId": "emp_cashier_07",
  "terminalId": "pos_term_berlin_02",
  "configurationVersion": 4
}

request payload-payload & beslissingscodes

De engine retourneert een van zeven canonieke decision-waarden: SUCCESS, FAILED, ALREADY_USED, ALREADY_VOIDED, EXPIRED, INVALID of PENDING (wanneer invoer door een operator vereist is via scanForm).

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "reasonCode": "RULE_ACCEPTED",
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true },
    { "rule": "ExpirationRule", "passed": true },
    { "rule": "LoyaltyProgramRule", "passed": true, "pointsDelta": 185 },
    { "rule": "TierEvaluationRule", "passed": true, "upgradedTo": "GOLD" }
  ],
  "passSnapshot": {
    "id": "pass_loy_449102",
    "templateId": "tmpl_loyalty_01",
    "serialNumber": "PI-LOY-449102",
    "externalId": "crm_cust_44910",
    "status": "ACTIVE",
    "tier": "GOLD",
    "barcodeValue": "PI-LOY-449102",
    "storedValue": "42.00"
  },
  "remainingBalance": "42.00",
  "effects": {
    "oldBalance": "42.00",
    "newBalance": "42.00",
    "pointsDelta": 185,
    "transactionAmount": 18.50,
    "currency": "EUR"
  },
  "display": {
    "title": "Scan Accepted — Gold Tier!",
    "subtitle": "+185 Points awarded",
    "color": "success"
  },
  "configurationVersion": 4,
  "configurationStale": false
}

Raadpleeg voor het controleren van voltooide scans en het exporteren van CSV-logboeken Scangeschiedenis & -resultaten.

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.