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

Scan-Verlauf & Ergebnisse

Prüfen Sie Scan-Ergebnisse (VALID, ALREADY_REDEEMED, EXPIRED, VOIDED), Zeitstempel, Standorte und Antwortdaten.

In dieser Anleitung

Überblick

Jede von Passinstance verarbeitete Validierungsanfrage erzeugt einen unveränderlichen Audit-Datensatz mit der ausgewerteten decision, dem reasonCode, dem schrittweisen ruleTrace, den Bediener-Metadaten sowie den Guthabenständen vor und nach dem Vorgang. Sie können Scan-Verläufe visuell im Dashboard unter Scanner (/scanner) einsehen, einzelne Scan-Belege prüfen, Ergebnisse idempotenter Vorgänge abfragen, nicht-mutierende Pass-Abfragen durchführen oder vollständige CSV-Exporte für die Buchhaltungsabstimmung streamen.

Wichtig: Schreibgeschützte Abfragerouten (GET /api/v1/scans/pass?barcode=... oder GET /api/v1/scans/pass/:barcodeValue) ermöglichen es POS-Terminals und Kundendienst-Schaltern, Pass-Status, externalId, Stufe und Guthaben abzurufen, ohne ein Scan-Ereignis aufzuzeichnen, Zähler zu erhöhen oder Einmal-Gutscheine zu entwerten.

Architektur & Ablauf der Audit-Abfrage

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
SCAN-BELEG- & AUDIT-EXPORT-PIPELINE
BETEILIGTE SYSTEMKOMPONENTEN
P1 POS / Scanner-Client
P2 Scan Validation API (/api/v1/scans)
P3 Validation Config API (/api/v1/validation)
SCHRITT 1 ANFRAGE / AKTION GET/scans/pass?barcode=...
SCHRITT 2 ANTWORT 200 OK (IPassLookupResponse)
SCHRITT 3 ANFRAGE / AKTION GET/scans/operations/:idem
SCHRITT 4 ANTWORT 200 OK (Cached ScanResponse)
SCHRITT 5 ANFRAGE / AKTION GET/scans/result/:scanId
SCHRITT 6 ANTWORT 200 OK (Full ruleTrace)
SCHRITT 7 ANFRAGE / AKTION GET/validation/scan-results/export/csv
SCHRITT 8 ANTWORT 200 OK (text/csv Stream: scan_id, decision, operator, effects)

Endpunkte für Scan-Abfrage, Audit & Export

MethodeEndpunktAuth / GuardBeschreibung
GET/api/v1/scans/passx-scanner-keySchreibgeschützte Pass-Abfrage über Query-Parameter ?barcode=... (empfohlen für URL-formatierte Payloads). Erzeugt keinen Scan-Datensatz.
GET/api/v1/scans/pass/:barcodeValuex-scanner-keySchreibgeschützte Pass-Abfrage per Pfad-Parameter; liefert IPassLookupResponse.
GET/api/v1/scans/result/:scanIdx-scanner-keyRuft das vollständige Ergebnis und ruleTrace eines bestimmten Scans anhand seiner UUID scanId ab.
GET/api/v1/scans/operations/:idempotencyKeyx-scanner-keyRuft den gespeicherten request payload-Beleg für einen zuvor übermittelten x-idempotency-key ab.
GET/api/v1/validation/scansArbeitsbereich-JWT / API-SchlüsselListet paginierte Scan-Protokolle des Arbeitsbereichs für das Dashboard (/scanner) auf.
GET/api/v1/validation/scans/:scanIdArbeitsbereich-JWT / API-SchlüsselRuft einen einzelnen Scan-Audit-Datensatz samt Trace für die Dashboard-Ansicht ab.
GET/api/v1/validation/configs/:id/scans/exportArbeitsbereich-JWT / API-SchlüsselExportiert den Scan-Verlauf für eine bestimmte ScannerConfiguration als CSV.
GET/api/v1/validation/scans/exportArbeitsbereich-JWT / API-SchlüsselExportiert arbeitsbereichsweite Scan- und Einlösungsprotokolle als CSV.
GET/api/v1/validation/scan-results/export/csvArbeitsbereich-JWT / API-SchlüsselStreamt das vollständige Scan-Audit-Protokoll einschließlich Regelauswertungen (text/csv).

Entscheidungs-Ergebnisse (request payload) vs. persistiertes scan status

Die API liefert ein übergeordnetes decision-Enum (SUCCESS | FAILED | ALREADY_USED | ALREADY_VOIDED | EXPIRED | INVALID | PENDING) in request payload zurück und speichert gleichzeitig das granulare scan status (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT) auf dem zugrunde liegenden Scan-Datensatz:

Entscheidung (request payload)StatusTypischer reasonCodeEmpfohlene Aktion für Personal / POS
SUCCESSACCEPTEDRULE_ACCEPTEDZutritt gewähren (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), Rabatt anwenden oder Guthabenabzug bestätigen.
ALREADY_VOIDEDREJECTEDPASS_VOIDED_AFTER_SCANEinlösung ablehnen; der Pass wurde bereits bei einem früheren Einmal-Scan verbraucht.
ALREADY_USEDREJECTEDONCE_PER_DAY_LIMIT_REACHEDPassinhaber informieren, dass das Tages- oder Check-in-Kontingent (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) ausgeschöpft ist.
EXPIREDREJECTEDPASS_EXPIREDKunden auf die Verlängerung der Mitgliedschaft oder eine aktive Kampagne hinweisen.
FAILEDREJECTEDOUT_OF_BALANCE / GEOFENCE_MISMATCHDetails in ruleTrace prüfen (z. B. unzureichendes Prepaid-Guthaben oder falscher Checkpoint).
INVALIDREJECTEDPASS_NOT_FOUND / INVALID_NONCEBarcode gehört nicht zu diesem Arbeitsbereich bzw. dieser Vorlage oder die Anti-Replay-Nonce ist abgelaufen.
PENDINGPENDINGOPERATOR_INPUT_REQUIREDKassenpersonal auffordern, erforderliche Felder in scanForm (etwa den Transaktionsbetrag) auszufüllen.

Abgeschlossenen Scan prüfen (GET /api/v1/scans/result/:scanId)

JSON
{
  "scanId": "scan_01hxyz7712ab",
  "idempotencyKey": "idem_reg04_20261116_0091",
  "timestamp": "2026-11-16T09:42:11.000Z",
  "decision": "ALREADY_USED",
  "status": "REJECTED",
  "reasonCode": "ONCE_PER_DAY_LIMIT_REACHED",
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true, "durationMs": 1 },
    { "rule": "ExpirationRule", "passed": true, "durationMs": 1 },
    {
      "rule": "OncePerDayRule",
      "passed": false,
      "reasonCode": "ONCE_PER_DAY_LIMIT_REACHED",
      "lastScanAt": "2026-11-16T06:15:04.000Z",
      "durationMs": 3
    }
  ],
  "passSnapshot": {
    "id": "pass_gym_8821",
    "templateId": "tmpl_gym_member",
    "serialNumber": "PI-GYM-8821",
    "externalId": "crm_member_8821",
    "status": "ACTIVE"
  }
}

Nicht-mutierende Pass-Abfrage (GET /api/v1/scans/pass)

Vor dem Übermitteln eines verändernden Scans oder einer POS-Abbuchung kann ein Terminal den aktuellen Zustand eines Passes über GET /api/v1/scans/pass?barcode=PI-GFT-550192 abfragen (bevorzugen Sie ?barcode= gegenüber dem Pfad-Parameter, wenn Barcodes Schrägstriche oder URLs enthalten):

GET /api/v1/scans/pass?barcode=PI-GFT-550192
Header
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "passId": "pass_gft_550192",
  "templateId": "tmpl_giftcard_eur",
  "templateName": "Retail Gift Card",
  "serialNumber": "PI-GFT-550192",
  "externalId": "shopify_cust_550192",
  "status": "ACTIVE",
  "storedValue": "75.00",
  "expirationDate": "2027-12-31T23:59:59.000Z",
  "isExpired": false,
  "isVoided": false,
  "barcodeValue": "PI-GFT-550192",
  "attributes": {
    "holderName": "Elena Rostova"
  },
  "checkedAt": "2026-11-16T10:15:00.000Z"
}

Scan-Protokolle als CSV exportieren

Für Schichtabstimmungen, Finanzprüfungen oder die BI-Übernahme exportieren Sie Scan-Verläufe direkt als UTF-8-CSV-Streams (Content-Type: text/csv; charset=utf-8):

  • Export einer einzelnen Konfiguration: GET /api/v1/validation/configs/:id/scans/export?from=2026-11-01&to=2026-11-16
  • Export aller Konfigurationen: GET /api/v1/validation/scans/export?templateId=tmpl_loyalty_01
  • Vollständiger Audit-Ergebnis-Export: GET /api/v1/validation/scan-results/export/csv

Weitere Optionen zur analytischen Auswertung finden Sie unter Scan- & Einlösungsberichte und Datenexporte & Reporting.

Weiterführende Produkt- & Entwicklerdoku

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.