Skip to content
Guía del Centro de ayuda · Escaneo de pases
4 min de lecturaVerificado 2026-11-16

Historial y resultados de escaneo

Audita resultados (VALID, ALREADY_REDEEMED, EXPIRED, VOIDED), marcas horarias, tiendas y respuestas.

En esta guía

Descripción general

Cada solicitud de validación procesada por Passinstance genera un registro de auditoría inmutable que incluye la decision evaluada, el reasonCode, el desglose paso a paso ruleTrace, los metadatos del operador y los saldos del pase antes y después de la operación. Puede consultar el historial de escaneos visualmente en el Panel de control en Escáner (/scanner), inspeccionar recibos de escaneo individuales, consultar resultados de operaciones idempotentes, realizar consultas de pase sin mutación o descargar exportaciones CSV completas para conciliación contable.

Importante: Las rutas de consulta de solo lectura (GET /api/v1/scans/pass?barcode=... o GET /api/v1/scans/pass/:barcodeValue) permiten a terminales POS y mostradores de atención al cliente consultar el estado del pase, externalId, nivel y saldo sin registrar un evento de escaneo, incrementar contadores ni anular cupones de un solo uso.

Arquitectura y flujo de consulta de auditoría

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
RECIBO DE ESCANEO Y CANALIZACIÓN DE EXPORTACIÓN DE AUDITORÍA
ACTORES DEL SISTEMA
P1 Cliente POS / Escáner
P2 Scan Validation API (/api/v1/scans)
P3 Validation Config API (/api/v1/validation)
PASO 1 SOLICITUD / ACCIÓN GET/scans/pass?barcode=...
PASO 2 RESPUESTA 200 OK (IPassLookupResponse)
PASO 3 SOLICITUD / ACCIÓN GET/scans/operations/:idem
PASO 4 RESPUESTA 200 OK (Cached ScanResponse)
PASO 5 SOLICITUD / ACCIÓN GET/scans/result/:scanId
PASO 6 RESPUESTA 200 OK (Full ruleTrace)
PASO 7 SOLICITUD / ACCIÓN GET/validation/scan-results/export/csv
PASO 8 RESPUESTA 200 OK (flujo text/csv: scan_id, decision, operator, effects)

Endpoints de consulta, auditoría y exportación de escaneos

MétodoEndpointAutenticación / GuardiaDescripción
GET/api/v1/scans/passx-scanner-keyConsulta de pase de solo lectura mediante parámetro de consulta ?barcode=... (recomendado para cargas útiles en formato URL). No crea un registro de escaneo.
GET/api/v1/scans/pass/:barcodeValuex-scanner-keyConsulta de pase de solo lectura mediante parámetro de ruta que devuelve IPassLookupResponse.
GET/api/v1/scans/result/:scanIdx-scanner-keyRecupera el resultado completo y ruleTrace de un escaneo específico mediante su UUID scanId.
GET/api/v1/scans/operations/:idempotencyKeyx-scanner-keyRecupera el recibo request payload almacenado para un x-idempotency-key enviado previamente.
GET/api/v1/validation/scansJWT del espacio de trabajo / API KeyLista los registros paginados de escaneo del espacio de trabajo para el Panel de control (/scanner).
GET/api/v1/validation/scans/:scanIdJWT del espacio de trabajo / API KeyObtiene un único registro de auditoría y traza de escaneo del espacio de trabajo para su inspección en el Panel de control.
GET/api/v1/validation/configs/:id/scans/exportJWT del espacio de trabajo / API KeyExporta en CSV el historial de escaneos limitado a una ScannerConfiguration concreta.
GET/api/v1/validation/scans/exportJWT del espacio de trabajo / API KeyExporta en CSV los registros de escaneo y canje de todo el espacio de trabajo.
GET/api/v1/validation/scan-results/export/csvJWT del espacio de trabajo / API KeyTransmite la pista de auditoría completa de escaneos incluyendo resultados de evaluación de reglas (text/csv).

Resultados de decisión (request payload) frente a scan status persistido

La API devuelve una enumeración de alto nivel decision (SUCCESS | FAILED | ALREADY_USED | ALREADY_VOIDED | EXPIRED | INVALID | PENDING) en request payload, mientras persiste la enumeración granular scan status (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT) en el registro subyacente del escaneo:

Decisión (request payload)Estado (status)reasonCode habitualAcción recomendada para personal / POS
SUCCESSACCEPTEDRULE_ACCEPTEDConceder acceso (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), aplicar descuento o confirmar deducción de saldo.
ALREADY_VOIDEDREJECTEDPASS_VOIDED_AFTER_SCANDenegar el canje; el pase ya fue consumido en un escaneo previo de un solo uso.
ALREADY_USEDREJECTEDONCE_PER_DAY_LIMIT_REACHEDInformar al titular que ya agotó su cupo diario o de entrada (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT).
EXPIREDREJECTEDPASS_EXPIREDIndicar al cliente que renueve su membresía o reclame una oferta de campaña activa.
FAILEDREJECTEDOUT_OF_BALANCE / GEOFENCE_MISMATCHRevisar el detalle de ruleTrace (por ejemplo, saldo prepago insuficiente o punto de control incorrecto).
INVALIDREJECTEDPASS_NOT_FOUND / INVALID_NONCEEl código de barras no pertenece a este espacio de trabajo o plantilla, o bien el nonce antirréplica caducó.
PENDINGPENDINGOPERATOR_INPUT_REQUIREDSolicitar al cajero que complete los campos obligatorios en scanForm (como el importe de la transacción).

Inspección de un escaneo completado (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"
  }
}

Consulta de pase sin mutación (GET /api/v1/scans/pass)

Antes de enviar un escaneo mutante o un débito POS, un terminal puede consultar el estado actual de un pase mediante GET /api/v1/scans/pass?barcode=PI-GFT-550192 (es preferible usar ?barcode= en lugar del parámetro de ruta siempre que los códigos de barras contengan barras o URL):

GET /api/v1/scans/pass?barcode=PI-GFT-550192
Encabezado
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"
}

Exportación de registros de escaneo a CSV

Para conciliación de turnos, auditorías financieras o ingesta en herramientas BI, exporte los historiales de escaneo directamente como flujos CSV UTF-8 (Content-Type: text/csv; charset=utf-8):

  • Exportación de una única configuración: GET /api/v1/validation/configs/:id/scans/export?from=2026-11-01&to=2026-11-16
  • Exportación de todas las configuraciones: GET /api/v1/validation/scans/export?templateId=tmpl_loyalty_01
  • Exportación completa de resultados de auditoría: GET /api/v1/validation/scan-results/export/csv

Consulte Informes de escaneo y canje y Exportaciones de datos e informes para conocer las opciones de agregación analítica.

Documentación de producto y API relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.