Überblick
Jeder Barcode-Scan oder kontaktlose NFC-Tap über die Mobile Scanner App, den Web-Scanner, die POS-Integration (POST /v1/pos/redeem und POST /v1/pos/scan), die Hardware-Reader-Orchestrierung (POST /api/v1/reader/redeem) oder die Scanner-Runtime-API (POST /api/v1/scans) erzeugt einen unveränderlichen, kryptografisch rückverfolgbaren Audit-Eintrag. Scan- & Einlösungsberichte (/scanner im Dashboard sowie /api/v1/validation/scans) aggregieren diese Ereignisse über Scanner-Konfigurationen, physische Validierungsorte, Bediener-IDs und Mechanik-Ledger hinweg und verschaffen Betriebsleitern vollständige Transparenz am Point of Sale.
Scan-Telemetrie & Regel-Trace-Pipeline
Wichtig: Jede Scan-Antwort protokolliert ein vollständiges
ruleTrace-Array zusammen mitoperatorId,terminalId,scannerConfigurationId,externalIdund GPS-location-Koordinaten — so können Compliance-Teams exakt nachvollziehen, warum ein Scan akzeptiert oder abgelehnt wurde.
Aufschlüsselung nach Scan-Metriken, scan status & PosOperation
Passinstance unterteilt den Validierungsverkehr in kanonische KPI-Kategorien gemäß PASS_ANALYTICS_METRIC_DEFINITIONS, gestützt auf decision in the scan response und 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):
| Metrikschlüssel | Zugrunde liegende decision / scan status | Betriebliche Bedeutung |
|---|---|---|
totalScans | Alle Scan-Ereignisse | Gesamtanzahl aller im Berichtszeitraum von der Validierungs-Engine empfangenen Barcode- oder NFC-Präsentationen. |
successfulScans | decision: 'SUCCESS' (SUCCESS, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS) | Scans, die alle 14 Validierungsregeln bestanden und ihre konfigurierte Anwesenheits- oder Mechanikaktion (scan action) ausgeführt haben. |
duplicateScans | decision: 'ALREADY_USED' oder 'ALREADY_VOIDED' (ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT) | Wiederholungsversuche bei Einmal-Gutscheinen (VOIDED_AFTER_SCAN scan mode) oder bereits ein-/ausgecheckten Pässen. |
expiredScans | decision: 'EXPIRED' (EXPIRED) | Vorzeigen von Pässen, deren expirationDate überschritten wurde. |
rejectedScans | decision: 'INVALID' (INVALID) | Unbekannte Barcode-Payloads, mandantenfremde Seriennummern oder ungültige kryptografische NFC-Signaturen. |
failedScans | decision: 'FAILED' (FAILED: z. B. OUT_OF_BALANCE, COOLDOWN_ACTIVE) | Gültige Pässe, die aufgrund einer Regelverletzung wie zu geringem Prepaid-Guthaben, Geofence-Abweichung oder OncePerDayRule-Sperrzeit abgelehnt wurden. |
Bei integrierten Kassen über POST /v1/pos/redeem erfassen Transaktionen zusätzlich PosOperation (DISCOUNT | ADD_POINTS | DEDUCT_VALUE | ADD_STAMPS | VOID | CUSTOM) und walletPropagation (PosWalletPropagationStatus: QUEUED | SKIPPED), abrufbar über GET /v1/pos/admin/logs.
Dimensionale Auswertung: Orte, Konfigurationen & Bediener
Validierungsberichte lassen sich entlang von fünf operativen Dimensionen filtern und gruppieren:
-
1
Scanner-Konfiguration (
scannerConfigurationId): Durchsatz zwischen einzelnen Profilen vergleichen (z. B. VIP-Gate-Check-In mitCHECK_IN scan modevs. Café-Kasse Stempeln mitStampCardAddRule). -
2
Validierungsort & Geofence: Einlösungen nach Filiale, Veranstaltungseingang oder GPS-Koordinatenradius gruppieren, um Besucherströme je Standort zu messen.
-
3
Bediener & Terminal (
operatorId,terminalId): Scan-Volumen und manuelle Betragseingaben je Kassenkraft, Gerätenamen (deviceName) oder POS-Kasse prüfen. -
4
Kanal & Protokoll (
channel,protocol): Optische Scans (QR,PDF417,CODE128,AZTEC) im Vergleich zu kontaktlosen Vorgängen (NFCviaVAS,SMART_TAP,NDEFoderJWT) verfolgen. -
5
Auswirkungen auf Wertguthaben & Treue-Ledger (
effects): SummiertestampsAdded, Netto-pointsDeltaund finanzielletransactionAmount-Gutschriften/-Abbuchungen nach Währung (ISO-4217) abstimmen.
Scan-Auditprotokolle & Ledger-Effekte per API abrufen
Schema erfasster Scan-Ereignisse & Ledger-Payloads
Bei der Abfrage der Scan-Historie (GET /api/v1/validation/configs/:id/scans oder GET /api/v1/scans/result/:scanId) liefert jedes Ereignis den vollständigen Diagnose- und Finanzkontext:
GET /api/v1/scans/result/scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c HTTP/1.1
Host: api.passinstance.com
x-scanner-key: <scanner_api_key>
Antwort-Payload (200 OK)
{
"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 }
]
}
Weiterführende Dokumentation
-
Vollständige Scan-Historien und Scanner-Schlüssel-Verzeichnisse exportieren in Datenexporte & Reporting.
-
Workspace-Telemetrie-Diagramme erkunden im Analytics Dashboard.
