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.

Belangrijk: Validatieregels worden atomair uitgevoerd op de server. Wanneer een scan de passtatus muteert (zoals
VOIDED_AFTER_SCANofStoredValueOperation.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-waarde | Gedrag & statusovergang | Typische toepassing |
|---|---|---|
SAVE_ATTENDANCE | Registreert een geldige scangebeurtenis en voert gekoppelde spaar-/stempelmechanica uit zonder de pas ongeldig te maken. | Spaarkaarten voor meerdere bezoeken, sportschoolabonnementen, seizoenskaarten. |
VOIDED_AFTER_SCAN | Zet de passtatus atomair om naar VOIDED bij de eerste geldige scan; volgende scans retourneren ALREADY_VOIDED. | Eenmalige coupons, promotievouchers, eenmalige toegangstickets. |
INVALIDATE_AFTER_SCAN | Markeert de pas als ongeldig na inwisseling en blokkeert toekomstige acceptatie onder de validatieconfiguratie. | Passen voor eenmalige inwisseling en beperkte gastvouchers. |
CHECK_IN | Zet de aanwezigheidsstatus van de pas op ingecheckt; weigert herhaalde check-ins als de bezoeker al binnen is. | Toegang tot conferentiesessies, gecontroleerde toegangspoorten. |
CHECK_OUT | Zet de aanwezigheidsstatus van de pas om van ingecheckt naar uitgecheckt. | Bijhouden van locatiebezetting, capaciteitsbeheer. |
CHECK_IN_CHECK_OUT_TOGGLE | Wisselt automatisch tussen CHECK_IN en CHECK_OUT bij opeenvolgende scans. | Co-workingspaces, meerdaagse festivalpolsbandjes/passen. |
2. Enumeraties voor opgeslagen tegoed, NFC & scanuitkomsten
| Enum-type | Toegestane waarden | Doel |
|---|---|---|
StoredValueOperation | NONE, ADD, SUBTRACT, SET | Bepaalt of een scan saldo's ongemoeid laat, tegoed opwaardeert (ADD), aankoopwaarde afboekt (SUBTRACT) of het saldo overschrijft (SET). |
StoredValueAmountSource | FIXED, OPERATOR, MECHANIC | Bepaalt of het transactiebedrag afkomstig is van een vooraf ingestelde configuratiewaarde (FIXED), invoer van de kassier (OPERATOR) of de sjabloonmechanica (MECHANIC). |
NfcReaderMode | AUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAP | Configureert protocolonderhandeling voor contactloze lezers voor Apple VAS en Google Smart Tap-terminals. |
| scan action | INCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOP | Actie die wordt vastgelegd op elke pasgebruik- of scangrootboektransactie (request payload staat ook SET toe). |
| scan status | SUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT | Granulaire 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):
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
/api/v1/scans/prepare
{
"scannedBarcodeValue": "PI-TKT-992014",
"scannerConfigurationId": "scfg_main_entrance_01"
}
Antwoord (201 Created)
{
"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
{
"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).
{
"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.
