Skip to content
Helpcentrum-gids · Passen scannen
4 min leestijdGecontroleerd 2026-11-16

Scangeschiedenis & resultaten

Controleer scanuitkomsten (VALID, ALREADY_REDEEMED, EXPIRED, VOIDED), tijdstippen en locaties.

In deze gids

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=... of GET /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

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
PIJPLIJN VOOR SCANBONNEN & AUDITEXPORTS
DEELNEMENDE SYSTEEMACTOREN
P1 POS / Scannerclient
P2 Scan Validation API (/api/v1/scans)
P3 Validation Config API (/api/v1/validation)
STAP 1 VERZOEK / ACTIE GET/scans/pass?barcode=...
STAP 2 ANTWOORD 200 OK (IPassLookupResponse)
STAP 3 VERZOEK / ACTIE GET/scans/operations/:idem
STAP 4 ANTWOORD 200 OK (Cached ScanResponse)
STAP 5 VERZOEK / ACTIE GET/scans/result/:scanId
STAP 6 ANTWOORD 200 OK (Volledige ruleTrace)
STAP 7 VERZOEK / ACTIE GET/validation/scan-results/export/csv
STAP 8 ANTWOORD 200 OK (text/csv-stream: scan_id, decision, operator, effects)

Endpoints voor scanopzoekingen, audits & exports

MethodeEndpointAuthenticatie / GuardBeschrijving
GET/api/v1/scans/passx-scanner-keyAlleen-lezen pasopzoeking via queryparameter ?barcode=... (aanbevolen voor URL-vormige payloads). Maakt geen scanrecord aan.
GET/api/v1/scans/pass/:barcodeValuex-scanner-keyAlleen-lezen pasopzoeking via padparameter die IPassLookupResponse retourneert.
GET/api/v1/scans/result/:scanIdx-scanner-keyHaalt het volledige resultaat en de ruleTrace van een specifieke scan op aan de hand van de UUID scanId.
GET/api/v1/scans/operations/:idempotencyKeyx-scanner-keyHaalt de opgeslagen request payload-bon op voor een eerder verzonden x-idempotency-key.
GET/api/v1/validation/scansWerkruimte-JWT / API KeyGeeft gepagineerde scanlogboeken van de werkruimte weer voor het Dashboard (/scanner).
GET/api/v1/validation/scans/:scanIdWerkruimte-JWT / API KeyHaalt één auditrecord en trace van een werkruimtescan op voor inspectie in het Dashboard.
GET/api/v1/validation/configs/:id/scans/exportWerkruimte-JWT / API KeyExporteert de scangeschiedenis voor een specifieke ScannerConfiguration als CSV.
GET/api/v1/validation/scans/exportWerkruimte-JWT / API KeyExporteert alle scan- en inwisselingslogboeken van de werkruimte als CSV.
GET/api/v1/validation/scan-results/export/csvWerkruimte-JWT / API KeyStreamt 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)StatusTypische reasonCodeAanbevolen actie voor medewerker / POS
SUCCESSACCEPTEDRULE_ACCEPTEDVerleen toegang (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), pas korting toe of bevestig saldoafschrijving.
ALREADY_VOIDEDREJECTEDPASS_VOIDED_AFTER_SCANWeiger inwisseling; de pas is al verbruikt bij een eerdere eenmalige scan.
ALREADY_USEDREJECTEDONCE_PER_DAY_LIMIT_REACHEDInformeer de pashouder dat de dagelijkse limiet of check-in (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) al is benut.
EXPIREDREJECTEDPASS_EXPIREDVerwijs de klant door om het lidmaatschap te verlengen of een actieve campagne-aanbieding te claimen.
FAILEDREJECTEDOUT_OF_BALANCE / GEOFENCE_MISMATCHControleer de details van ruleTrace (bijv. onvoldoende prepaid-saldo of verkeerd controlepunt).
INVALIDREJECTEDPASS_NOT_FOUND / INVALID_NONCEBarcode hoort niet bij deze werkruimte/sjabloon of de anti-replay-nonce is verlopen.
PENDINGPENDINGOPERATOR_INPUT_REQUIREDVraag de kassier om de vereiste velden in scanForm in te vullen (zoals het transactiebedrag).

Een voltooide scan inspecteren (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"
  }
}

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):

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"
}

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.

Gerelateerde product- en ontwikkelaarsdocs

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.