Skip to content
Helpcentrum-gids
3 min leestijdGecontroleerd 2026-11-16

Scan- & inwisselingsrapporten

Analyseer scanvolumes per validatieplek, spaarpunt- en voucherstatistieken en bezoekfrequentie.

In deze gids

Overzicht

Elke barcodescan of contactloze NFC-tap die wordt verwerkt via de Mobiele Scanner-app, Webscanner, POS-koppeling (POST /v1/pos/redeem en POST /v1/pos/scan), Hardware-lezerorkestratie (POST /api/v1/reader/redeem) of Scanner Runtime API (POST /api/v1/scans) genereert een onveranderlijk, cryptografisch traceerbaar auditrecord. Scan- & verzilveringsrapportages (/scanner in het Dashboard en /api/v1/validation/scans) groeperen deze gebeurtenissen per scannerconfiguratie, fysieke validatielocatie, operator-ID en mechaniek-grootboek om operationeel managers volledig inzicht op de werkvloer te bieden.

Pijplijn voor scantelemetrie & regeltracering

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
SCANVALIDATIE- & VERZILVERINGSTELEMETRIE
FASE 01 INVOERKANALEN VOOR SCANNERS & POS
Mobiele / Webscanner
POST/api/v1/scans
Winkel-POS-terminal
POST/v1/pos/redeem
Hardware NFC-lezer
`/api/v1/reader/redeem
FASE 02 VALIDATIE-ENGINE MET 14 BEDRIJFSREGELS
1
Basisregels: PassStatusRuleExpirationRuleTimeWindowRule
GeofencingRule
2
Mechanieken: OncePerDayRuleStampCardAddRulePrepaidCardRule
LoyaltyProgramRuleTierEvaluationRule
3
Beveiliging: RateLimitRuleAntiReplayRule (scan nonce)
FASE 03 SCANANALYTIEK & GROOTBOEK-RAPPORTAGEOPSLAG
scan status-indeling
(SUCCESS, EXPIRED, CHECK_IN_SUCCESS...)
Dimensionale splitsing
(scannerConfigId, operatorId, Loc.)
Tegoed- &
punten-mutatie grootboektotalen

Belangrijk: Elk scanantwoord legt een volledige ruleTrace-lijst vast naast operatorId, terminalId, scannerConfigurationId, externalId en GPS-location-coördinaten—zo kunnen complianceteams exact controleren waarom een scan is geaccepteerd of geweigerd.

Scanstatistieken, scan status & PosOperation-overzicht

Passinstance deelt validatieverkeer in canonieke KPI-categorieën in binnen PASS_ANALYTICS_METRIC_DEFINITIONS, ondersteund door decision in the scan response en Passinstance database scan status (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT):

StatistieksleutelOnderliggende decision / scan statusOperationele betekenis
totalScansAlle scangebeurtenissenTotaal aantal ontvangen barcode- of NFC-aanbiedingen binnen de rapportageperiode.
successfulScansdecision: 'SUCCESS' (SUCCESS, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS)Scans die alle 14 validatieregels doorstonden en de geconfigureerde aanwezigheids- of mechaniekactie (scan action) uitvoerden.
duplicateScansdecision: 'ALREADY_USED' of 'ALREADY_VOIDED' (ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT)Herhaalde pogingen op eenmalige coupons (VOIDED_AFTER_SCAN scan mode) of al in-/uitgecheckte passen.
expiredScansdecision: 'EXPIRED' (EXPIRED)Aanbiedingen van passen waarvan de expirationDate is verstreken.
rejectedScansdecision: 'INVALID' (INVALID)Onbekende barcodegegevens, serienummers uit een andere tenant of ongeldige cryptografische NFC-handtekeningen.
failedScansdecision: 'FAILED' (FAILED: bijv. OUT_OF_BALANCE, COOLDOWN_ACTIVE)Geldige passen die zijn geweigerd wegens een bedrijfsregel zoals ontoereikend prepaidtegoed, geofence-afwijking of OncePerDayRule-wachttijd.

Voor geïntegreerde kassa's die POST /v1/pos/redeem aanroepen registreren transacties ook PosOperation (DISCOUNT | ADD_POINTS | DEDUCT_VALUE | ADD_STAMPS | VOID | CUSTOM) en walletPropagation (PosWalletPropagationStatus: QUEUED | SKIPPED), opvraagbaar via GET /v1/pos/admin/logs.

Dimensionale rapportages: locaties, configuraties en operators

Validatierapporten kunnen over vijf operationele dimensies worden gefilterd en gegroepeerd:

  1. 1
    Scannerconfiguratie (scannerConfigurationId): Vergelijk de doorvoer tussen profielen (bijv. VIP-ingang check-in met CHECK_IN scan mode vs. Kassa Stempel toevoegen met StampCardAddRule).
  2. 2
    Validatielocatie & geofence: Groepeer verzilveringen per filiaal, evenementingang of GPS-coördinaatstraal om bezoekersdrukte per fysieke locatie te meten.
  3. 3
    Operator & terminal (operatorId, terminalId): Controleer scanvolumes en handmatige bedraginvoer per kassamedewerker, apparaatnaam (deviceName) of POS-kassa.
  4. 4
    Kanaal & protocol (channel, protocol): Volg optische scans (QR, PDF417, CODE128, AZTEC) versus contactloze taps (NFC via VAS, SMART_TAP, NDEF of JWT).
  5. 5
    Tegoed- & loyaliteitsgrootboekeffecten (effects): Stem het totaal aan stampsAdded, netto pointsDelta en financiële transactionAmount-bijschrijvingen en -afschrijvingen af per valuta (ISO-4217).

Scanauditlogboeken & grootboekeffecten inspecteren via API

Schema van geregistreerde scangebeurtenissen & grootboekpayloads

Bij het opvragen van scanhistorie (GET /api/v1/validation/configs/:id/scans of GET /api/v1/scans/result/:scanId) levert elke gebeurtenis de volledige diagnostische en financiële context:

HTTP
GET /api/v1/scans/result/scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c HTTP/1.1
Host: api.passinstance.com
x-scanner-key: <scanner_api_key>

Antwoordpayload (200 OK)

JSON
{
  "scanId": "scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c",
  "timestamp": "2026-11-16T08:42:11.304Z",
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "reasonCode": null,
  "channel": "NFC",
  "protocol": "VAS",
  "resolvedConfigId": "cfg_7d82a100-3c4b-4e12-9a88-112233445566",
  "passSnapshot": {
    "id": "pas_55a19c88-102b-4f33-8d99-ccddff001122",
    "templateId": "b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
    "serialNumber": "PI-2026-994812",
    "externalId": "CRM-88210",
    "status": "ACTIVE",
    "tier": "GOLD"
  },
  "effects": {
    "oldBalance": "45.00",
    "newBalance": "32.50",
    "transactionAmount": 12.50,
    "currency": "EUR",
    "amountBalanceBehavior": "ADD_VALUE",
    "pointsDelta": 125,
    "stampsAdded": 0
  },
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true },
    { "rule": "ExpirationRule", "passed": true },
    { "rule": "PrepaidCardRule", "passed": true, "deducted": 12.50 },
    { "rule": "LoyaltyProgramRule", "passed": true, "awardedPoints": 125 }
  ]
}

Gerelateerde documentatie

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.