Overzicht
Elk validatieverzoek dat door Passinstance wordt verwerkt, genereert een onveranderlijk auditrecord met de geëvalueerde decision, reasonCode, stapsgewijze ruleTrace, operatormetadata en passaldo's voor en na de transactie. U kunt scangeschiedenissen visueel bekijken in het Dashboard onder Scanner (/scanner), individuele scanbonnen inspecteren, uitkomsten van idempotente bewerkingen opvragen, niet-muterende pasopzoekingen uitvoeren of volledige CSV-exports streamen voor boekhoudkundige afstemming.
Belangrijk: Alleen-lezen opzoekroutes (
GET /api/v1/scans/pass?barcode=...ofGET /api/v1/scans/pass/:barcodeValue) stellen POS-terminals en klantenservicebalies in staat om passtatus,externalId, tier en saldo te inspecteren zonder een scangebeurtenis vast te leggen, tellers te verhogen of eenmalige vouchers ongeldig te maken.
Architectuur & stroom voor auditopzoekingen
Endpoints voor scanopzoekingen, audits & exports
| Methode | Endpoint | Authenticatie / Guard | Beschrijving |
|---|---|---|---|
| GET | /api/v1/scans/pass | x-scanner-key | Alleen-lezen pasopzoeking via queryparameter ?barcode=... (aanbevolen voor URL-vormige payloads). Maakt geen scanrecord aan. |
| GET | /api/v1/scans/pass/:barcodeValue | x-scanner-key | Alleen-lezen pasopzoeking via padparameter die IPassLookupResponse retourneert. |
| GET | /api/v1/scans/result/:scanId | x-scanner-key | Haalt het volledige resultaat en de ruleTrace van een specifieke scan op aan de hand van de UUID scanId. |
| GET | /api/v1/scans/operations/:idempotencyKey | x-scanner-key | Haalt de opgeslagen request payload-bon op voor een eerder verzonden x-idempotency-key. |
| GET | /api/v1/validation/scans | Werkruimte-JWT / API Key | Geeft gepagineerde scanlogboeken van de werkruimte weer voor het Dashboard (/scanner). |
| GET | /api/v1/validation/scans/:scanId | Werkruimte-JWT / API Key | Haalt één auditrecord en trace van een werkruimtescan op voor inspectie in het Dashboard. |
| GET | /api/v1/validation/configs/:id/scans/export | Werkruimte-JWT / API Key | Exporteert de scangeschiedenis voor een specifieke ScannerConfiguration als CSV. |
| GET | /api/v1/validation/scans/export | Werkruimte-JWT / API Key | Exporteert alle scan- en inwisselingslogboeken van de werkruimte als CSV. |
| GET | /api/v1/validation/scan-results/export/csv | Werkruimte-JWT / API Key | Streamt het volledige scanauditspoor inclusief uitkomsten van regelevaluaties (text/csv). |
Beslissingsuitkomsten (request payload) vs. opgeslagen scan status
De API retourneert een hoog-niveau decision-enum (SUCCESS | FAILED | ALREADY_USED | ALREADY_VOIDED | EXPIRED | INVALID | PENDING) in request payload, terwijl de granulaire scan status (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT) op het onderliggende scanrecord wordt opgeslagen:
Beslissing (request payload) | Status | Typische reasonCode | Aanbevolen actie voor medewerker / POS |
|---|---|---|---|
SUCCESS | ACCEPTED | RULE_ACCEPTED | Verleen toegang (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), pas korting toe of bevestig saldoafschrijving. |
ALREADY_VOIDED | REJECTED | PASS_VOIDED_AFTER_SCAN | Weiger inwisseling; de pas is al verbruikt bij een eerdere eenmalige scan. |
ALREADY_USED | REJECTED | ONCE_PER_DAY_LIMIT_REACHED | Informeer de pashouder dat de dagelijkse limiet of check-in (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) al is benut. |
EXPIRED | REJECTED | PASS_EXPIRED | Verwijs de klant door om het lidmaatschap te verlengen of een actieve campagne-aanbieding te claimen. |
FAILED | REJECTED | OUT_OF_BALANCE / GEOFENCE_MISMATCH | Controleer de details van ruleTrace (bijv. onvoldoende prepaid-saldo of verkeerd controlepunt). |
INVALID | REJECTED | PASS_NOT_FOUND / INVALID_NONCE | Barcode hoort niet bij deze werkruimte/sjabloon of de anti-replay-nonce is verlopen. |
PENDING | PENDING | OPERATOR_INPUT_REQUIRED | Vraag de kassier om de vereiste velden in scanForm in te vullen (zoals het transactiebedrag). |
Een voltooide scan inspecteren (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"
}
}
Niet-muterende pasopzoeking (GET /api/v1/scans/pass)
Voordat een muterende scan of POS-afschrijving wordt ingediend, kan een terminal de huidige status van een pas opvragen via GET /api/v1/scans/pass?barcode=PI-GFT-550192 (geef de voorkeur aan ?barcode= boven de padparameter wanneer barcodes slashes of URL's bevatten):
/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"
}
Scanlogboeken exporteren naar CSV
Voor dienstenafsluiting, financiële audits of BI-import exporteert u scangeschiedenissen rechtstreeks als UTF-8 CSV-streams (Content-Type: text/csv; charset=utf-8):
-
Export voor één configuratie:
GET /api/v1/validation/configs/:id/scans/export?from=2026-11-01&to=2026-11-16 -
Export voor alle configuraties:
GET /api/v1/validation/scans/export?templateId=tmpl_loyalty_01 -
Volledige export van auditresultaten:
GET /api/v1/validation/scan-results/export/csv
Raadpleeg Scan- & inwisselingsrapporten en Gegevensexports & rapportage voor opties voor analytics-aggregatie.
