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=...oGET /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
Endpoints de consulta, auditoría y exportación de escaneos
| Método | Endpoint | Autenticación / Guardia | Descripción |
|---|---|---|---|
| GET | /api/v1/scans/pass | x-scanner-key | Consulta 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/:barcodeValue | x-scanner-key | Consulta de pase de solo lectura mediante parámetro de ruta que devuelve IPassLookupResponse. |
| GET | /api/v1/scans/result/:scanId | x-scanner-key | Recupera el resultado completo y ruleTrace de un escaneo específico mediante su UUID scanId. |
| GET | /api/v1/scans/operations/:idempotencyKey | x-scanner-key | Recupera el recibo request payload almacenado para un x-idempotency-key enviado previamente. |
| GET | /api/v1/validation/scans | JWT del espacio de trabajo / API Key | Lista los registros paginados de escaneo del espacio de trabajo para el Panel de control (/scanner). |
| GET | /api/v1/validation/scans/:scanId | JWT del espacio de trabajo / API Key | Obtiene 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/export | JWT del espacio de trabajo / API Key | Exporta en CSV el historial de escaneos limitado a una ScannerConfiguration concreta. |
| GET | /api/v1/validation/scans/export | JWT del espacio de trabajo / API Key | Exporta en CSV los registros de escaneo y canje de todo el espacio de trabajo. |
| GET | /api/v1/validation/scan-results/export/csv | JWT del espacio de trabajo / API Key | Transmite 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 habitual | Acción recomendada para personal / POS |
|---|---|---|---|
SUCCESS | ACCEPTED | RULE_ACCEPTED | Conceder acceso (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), aplicar descuento o confirmar deducción de saldo. |
ALREADY_VOIDED | REJECTED | PASS_VOIDED_AFTER_SCAN | Denegar el canje; el pase ya fue consumido en un escaneo previo de un solo uso. |
ALREADY_USED | REJECTED | ONCE_PER_DAY_LIMIT_REACHED | Informar al titular que ya agotó su cupo diario o de entrada (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT). |
EXPIRED | REJECTED | PASS_EXPIRED | Indicar al cliente que renueve su membresía o reclame una oferta de campaña activa. |
FAILED | REJECTED | OUT_OF_BALANCE / GEOFENCE_MISMATCH | Revisar el detalle de ruleTrace (por ejemplo, saldo prepago insuficiente o punto de control incorrecto). |
INVALID | REJECTED | PASS_NOT_FOUND / INVALID_NONCE | El código de barras no pertenece a este espacio de trabajo o plantilla, o bien el nonce antirréplica caducó. |
PENDING | PENDING | OPERATOR_INPUT_REQUIRED | Solicitar 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)
{
"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):
/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"
}
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.
