Descripción general
Cada lectura de código de barras o toque NFC sin contacto procesado mediante la app móvil de escaneo, el escáner web, la integración TPV (POS) (POST /v1/pos/redeem y POST /v1/pos/scan), la orquestación de lectores hardware (POST /api/v1/reader/redeem) o la API de ejecución de escaneo (POST /api/v1/scans) genera un registro de auditoría inmutable y criptográficamente trazable. Los informes de escaneo y canje (/scanner en el Panel y /api/v1/validation/scans) consolidan estos eventos por configuración de escáner, lugar de validación físico, ID de operador y libro mayor de mecánicas para ofrecer visibilidad operativa completa.
Canalización de telemetría de escaneo y traza de reglas
Importante: Cada respuesta de escaneo guarda un arreglo completo
ruleTracejunto conoperatorId,terminalId,scannerConfigurationId,externalIdy coordenadas GPSlocation, permitiendo a los equipos de cumplimiento auditar con precisión por qué se aceptó o rechazó un escaneo.
Definición de métricas, scan status y desglose de PosOperation
Passinstance clasifica el tráfico de validación en indicadores canónicos definidos en PASS_ANALYTICS_METRIC_DEFINITIONS, respaldados por decision in the scan response y scan status de Passinstance database (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT):
| Clave de métrica | decision / scan status subyacente | Significado operativo |
|---|---|---|
totalScans | Todos los eventos | Total de lecturas de código de barras o NFC recibidas por el motor de validación en el período consultado. |
successfulScans | decision: 'SUCCESS' (SUCCESS, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS) | Escaneos que superaron las 14 reglas de validación y ejecutaron su acción de asistencia o mecánica (scan action). |
duplicateScans | decision: 'ALREADY_USED' o 'ALREADY_VOIDED' (ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT) | Intentos repetidos en cupones de un solo uso (VOIDED_AFTER_SCAN scan mode) o pases ya registrados de entrada/salida. |
expiredScans | decision: 'EXPIRED' (EXPIRED) | Presentación de pases cuya expirationDate ya ha vencido. |
rejectedScans | decision: 'INVALID' (INVALID) | Códigos de barras desconocidos, series de otro inquilino o firmas NFC criptográficas inválidas. |
failedScans | decision: 'FAILED' (FAILED: p. ej., OUT_OF_BALANCE, COOLDOWN_ACTIVE) | Pases válidos rechazados por una regla de negocio como saldo insuficiente, fuera de geovalla o enfriamiento de OncePerDayRule. |
En cajas integradas que llaman a POST /v1/pos/redeem, las transacciones registran además PosOperation (DISCOUNT | ADD_POINTS | DEDUCT_VALUE | ADD_STAMPS | VOID | CUSTOM) y walletPropagation (PosWalletPropagationStatus: QUEUED | SKIPPED), inspeccionables vía GET /v1/pos/admin/logs.
Informes dimensionales: lugares, configuraciones y operadores
Los informes de validación se filtran y agrupan en cinco dimensiones operativas:
-
1
Configuración de escáner (
scannerConfigurationId): Compare el volumen entre perfiles distintos (por ejemplo, Acceso VIP conCHECK_IN scan modefrente a Caja cafetería Añadir sellos conStampCardAddRule). -
2
Lugar de validación y geovalla: Agrupe canjes por tienda, puerta de recinto o radio de coordenadas GPS para medir afluencia por ubicación física.
-
3
Operador y terminal (
operatorId,terminalId): Audite lecturas e importes introducidos manualmente por cajero, nombre de dispositivo (deviceName) o caja POS. -
4
Canal y protocolo (
channel,protocol): Compare escaneos ópticos (QR,PDF417,CODE128,AZTEC) frente a lecturas sin contacto (NFCvíaVAS,SMART_TAP,NDEFoJWT). -
5
Efectos de saldo y puntos (
effects): Concilie el total destampsAdded, la variación netapointsDeltay abonos/cargostransactionAmountpor divisa (ISO-4217).
Inspección de registros de escaneo y efectos de libro mayor vía API
Esquema de evento de escaneo y payload de libro mayor
Al consultar el historial de escaneos (GET /api/v1/validation/configs/:id/scans o GET /api/v1/scans/result/:scanId), cada evento devuelve el contexto diagnóstico y financiero completo:
GET /api/v1/scans/result/scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c HTTP/1.1
Host: api.passinstance.com
x-scanner-key: <scanner_api_key>
Payload de respuesta (200 OK)
{
"scanId": "scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c",
"timestamp": "2026-11-16T08:42:11.304Z",
"decision": "SUCCESS",
"status": "ACCEPTED",
"reasonCode": null,
"channel": "NFC",
"protocol": "VAS",
"resolvedConfigId": "cfg_7d82a100-3c4b-4e12-9a88-112233445566",
"passSnapshot": {
"id": "pas_55a19c88-102b-4f33-8d99-ccddff001122",
"templateId": "b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
"serialNumber": "PI-2026-994812",
"externalId": "CRM-88210",
"status": "ACTIVE",
"tier": "GOLD"
},
"effects": {
"oldBalance": "45.00",
"newBalance": "32.50",
"transactionAmount": 12.50,
"currency": "EUR",
"amountBalanceBehavior": "ADD_VALUE",
"pointsDelta": 125,
"stampsAdded": 0
},
"ruleTrace": [
{ "rule": "PassStatusRule", "passed": true },
{ "rule": "ExpirationRule", "passed": true },
{ "rule": "PrepaidCardRule", "passed": true, "deducted": 12.50 },
{ "rule": "LoyaltyProgramRule", "passed": true, "awardedPoints": 125 }
]
}
Documentación relacionada
-
Exporte historiales completos de escaneo e inventarios de claves en Exportación de datos e informes.
-
Explore gráficos de telemetría del espacio de trabajo en el Panel de analítica.
