Skip to content
Guía del Centro de ayuda
3 min de lecturaVerificado 2026-11-16

Informes de escaneo y canje

Revisa volumen por lugar de validación, totales acumulados de mecánicas y recurrencia de clientes.

En esta guía

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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
TELEMETRÍA DE VALIDACIÓN Y CANJE DE ESCANEOS
ETAPA 01 CANALES DE INGESTA DE ESCÁNER Y TPV
Escáner móvil / web
POST/api/v1/scans
Terminal POS de tienda
POST/v1/pos/redeem
Lector NFC hardware
`/api/v1/reader/redeem
ETAPA 02 MOTOR DE VALIDACIÓN DE NEGOCIO DE 14 REGLAS
1
Reglas base: PassStatusRuleExpirationRuleTimeWindowRule
GeofencingRule
2
Mecánicas: OncePerDayRuleStampCardAddRulePrepaidCardRule
LoyaltyProgramRuleTierEvaluationRule
3
Seguridad: RateLimitRuleAntiReplayRule (scan nonce)
ETAPA 03 ALMACÉN DE ANALÍTICA Y REPORTES DE ESCANEO
Desglose scan status| | S
(SUCCESS, EXPIRED, CHECK_IN_SUCCESS...)
mentación dimens. | | A
(scannerConfigId, operatorId, Lugar)
egados de saldo
y delta de puntos del libro mayor

Importante: Cada respuesta de escaneo guarda un arreglo completo ruleTrace junto con operatorId, terminalId, scannerConfigurationId, externalId y coordenadas GPS location, 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étricadecision / scan status subyacenteSignificado operativo
totalScansTodos los eventosTotal de lecturas de código de barras o NFC recibidas por el motor de validación en el período consultado.
successfulScansdecision: '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).
duplicateScansdecision: '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.
expiredScansdecision: 'EXPIRED' (EXPIRED)Presentación de pases cuya expirationDate ya ha vencido.
rejectedScansdecision: 'INVALID' (INVALID)Códigos de barras desconocidos, series de otro inquilino o firmas NFC criptográficas inválidas.
failedScansdecision: '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. 1
    Configuración de escáner (scannerConfigurationId): Compare el volumen entre perfiles distintos (por ejemplo, Acceso VIP con CHECK_IN scan mode frente a Caja cafetería Añadir sellos con StampCardAddRule).
  2. 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. 3
    Operador y terminal (operatorId, terminalId): Audite lecturas e importes introducidos manualmente por cajero, nombre de dispositivo (deviceName) o caja POS.
  4. 4
    Canal y protocolo (channel, protocol): Compare escaneos ópticos (QR, PDF417, CODE128, AZTEC) frente a lecturas sin contacto (NFC vía VAS, SMART_TAP, NDEF o JWT).
  5. 5
    Efectos de saldo y puntos (effects): Concilie el total de stampsAdded, la variación neta pointsDelta y abonos/cargos transactionAmount por 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:

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

JSON
{
  "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

¿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.