Ü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=...oderGET /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
Endpunkte für Scan-Abfrage, Audit & Export
| Methode | Endpunkt | Auth / Guard | Beschreibung |
|---|---|---|---|
| GET | /api/v1/scans/pass | x-scanner-key | Schreibgeschützte Pass-Abfrage über Query-Parameter ?barcode=... (empfohlen für URL-formatierte Payloads). Erzeugt keinen Scan-Datensatz. |
| GET | /api/v1/scans/pass/:barcodeValue | x-scanner-key | Schreibgeschützte Pass-Abfrage per Pfad-Parameter; liefert IPassLookupResponse. |
| GET | /api/v1/scans/result/:scanId | x-scanner-key | Ruft das vollständige Ergebnis und ruleTrace eines bestimmten Scans anhand seiner UUID scanId ab. |
| GET | /api/v1/scans/operations/:idempotencyKey | x-scanner-key | Ruft den gespeicherten request payload-Beleg für einen zuvor übermittelten x-idempotency-key ab. |
| GET | /api/v1/validation/scans | Arbeitsbereich-JWT / API-Schlüssel | Listet paginierte Scan-Protokolle des Arbeitsbereichs für das Dashboard (/scanner) auf. |
| GET | /api/v1/validation/scans/:scanId | Arbeitsbereich-JWT / API-Schlüssel | Ruft einen einzelnen Scan-Audit-Datensatz samt Trace für die Dashboard-Ansicht ab. |
| GET | /api/v1/validation/configs/:id/scans/export | Arbeitsbereich-JWT / API-Schlüssel | Exportiert den Scan-Verlauf für eine bestimmte ScannerConfiguration als CSV. |
| GET | /api/v1/validation/scans/export | Arbeitsbereich-JWT / API-Schlüssel | Exportiert arbeitsbereichsweite Scan- und Einlösungsprotokolle als CSV. |
| GET | /api/v1/validation/scan-results/export/csv | Arbeitsbereich-JWT / API-Schlüssel | Streamt 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) | Status | Typischer reasonCode | Empfohlene Aktion für Personal / POS |
|---|---|---|---|
SUCCESS | ACCEPTED | RULE_ACCEPTED | Zutritt gewähren (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), Rabatt anwenden oder Guthabenabzug bestätigen. |
ALREADY_VOIDED | REJECTED | PASS_VOIDED_AFTER_SCAN | Einlösung ablehnen; der Pass wurde bereits bei einem früheren Einmal-Scan verbraucht. |
ALREADY_USED | REJECTED | ONCE_PER_DAY_LIMIT_REACHED | Passinhaber informieren, dass das Tages- oder Check-in-Kontingent (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) ausgeschöpft ist. |
EXPIRED | REJECTED | PASS_EXPIRED | Kunden auf die Verlängerung der Mitgliedschaft oder eine aktive Kampagne hinweisen. |
FAILED | REJECTED | OUT_OF_BALANCE / GEOFENCE_MISMATCH | Details in ruleTrace prüfen (z. B. unzureichendes Prepaid-Guthaben oder falscher Checkpoint). |
INVALID | REJECTED | PASS_NOT_FOUND / INVALID_NONCE | Barcode gehört nicht zu diesem Arbeitsbereich bzw. dieser Vorlage oder die Anti-Replay-Nonce ist abgelaufen. |
PENDING | PENDING | OPERATOR_INPUT_REQUIRED | Kassenpersonal auffordern, erforderliche Felder in scanForm (etwa den Transaktionsbetrag) auszufüllen. |
Abgeschlossenen Scan prüfen (GET /api/v1/scans/result/:scanId)
{
"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):
/api/v1/scans/pass?barcode=PI-GFT-550192
{
"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.
