Skip to content
Hilfecenter-Anleitung
3 Min. LesezeitGeprüft 2026-11-16

Scan- & Einlösungsberichte

Werten Sie Check-ins pro Validation Place, Einlösungssummen von Mechaniken und Besuchsfrequenzen aus.

In dieser Anleitung

Ü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

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
SCAN-VALIDIERUNGS- & EINLÖSUNGS-TELEMETRIE
STUFE 01 SCANNER- & POS-ERFASSUNGSKANÄLE
Mobile / Web-Scanner
POST/api/v1/scans
Kassen-POS-Terminal
POST/v1/pos/redeem
Hardware-NFC-Reader
`/api/v1/reader/redeem
STUFE 02 14-REGEL-GESCHÄFTSVALIDIERUNGS-ENGINE
1
Kernregeln: PassStatusRuleExpirationRuleTimeWindowRule
GeofencingRule
2
Mechaniken: OncePerDayRuleStampCardAddRulePrepaidCardRule
LoyaltyProgramRuleTierEvaluationRule
3
Sicherheit: RateLimitRuleAntiReplayRule (scan nonce)
STUFE 03 SCAN-ANALYTIK & LEDGER-BERICHTSSPEICHER
scan status-Aufschl.
(SUCCESS, EXPIRED, CHECK_IN_SUCCESS...)
Dimensionale Filter
(scannerConfigId, operatorId, Ort)
Guthaben- &
Punkte-Delta-
Ledger-Summen

Wichtig: Jede Scan-Antwort protokolliert ein vollständiges ruleTrace-Array zusammen mit operatorId, terminalId, scannerConfigurationId, externalId und 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üsselZugrunde liegende decision / scan statusBetriebliche Bedeutung
totalScansAlle Scan-EreignisseGesamtanzahl aller im Berichtszeitraum von der Validierungs-Engine empfangenen Barcode- oder NFC-Präsentationen.
successfulScansdecision: '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.
duplicateScansdecision: '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.
expiredScansdecision: 'EXPIRED' (EXPIRED)Vorzeigen von Pässen, deren expirationDate überschritten wurde.
rejectedScansdecision: 'INVALID' (INVALID)Unbekannte Barcode-Payloads, mandantenfremde Seriennummern oder ungültige kryptografische NFC-Signaturen.
failedScansdecision: '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. 1
    Scanner-Konfiguration (scannerConfigurationId): Durchsatz zwischen einzelnen Profilen vergleichen (z. B. VIP-Gate-Check-In mit CHECK_IN scan mode vs. Café-Kasse Stempeln mit StampCardAddRule).
  2. 2
    Validierungsort & Geofence: Einlösungen nach Filiale, Veranstaltungseingang oder GPS-Koordinatenradius gruppieren, um Besucherströme je Standort zu messen.
  3. 3
    Bediener & Terminal (operatorId, terminalId): Scan-Volumen und manuelle Betragseingaben je Kassenkraft, Gerätenamen (deviceName) oder POS-Kasse prüfen.
  4. 4
    Kanal & Protokoll (channel, protocol): Optische Scans (QR, PDF417, CODE128, AZTEC) im Vergleich zu kontaktlosen Vorgängen (NFC via VAS, SMART_TAP, NDEF oder JWT) verfolgen.
  5. 5
    Auswirkungen auf Wertguthaben & Treue-Ledger (effects): Summierte stampsAdded, Netto-pointsDelta und finanzielle transactionAmount-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:

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>

Antwort-Payload (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 }
  ]
}

Weiterführende Dokumentation

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.