Skip to content
Guía del Centro de ayuda · Escaneo de pasesFase de incorporación 4
4 min de lecturaVerificado 2026-11-16

Modos de escaneo y reglas de validación

Configura canje único, entrada/salida, límite diario, mensajes en caja y caché en modo sin conexión.

En esta guía

Recorridos visuales interactivos

Abrir en la guía de 6 fases

Inspecciona las pantallas reales del panel y las anotaciones ampliadas de esta guía.

Enfoque de interfaz ampliado
Elementos clave de la interfaz

Mensaje posterior al escaneo y configuraciones de escáner (Zoom)

Personaliza el mensaje de confirmación del operador usando marcadores como {holderName} y gestiona los enlaces de acceso activos.

Descripción general

Cada escaneo enviado a POST /api/v1/scans se evalúa frente a la ScannerConfiguration activa (resuelta mediante la clave x-scanner-key asociada o mediante scannerConfigurationId / validationConfigId en request payload) y una canalización determinista Validation Rules Engine de 14 reglas. En conjunto, estos ajustes determinan si un pase registra asistencia, se anula tras un único uso, alterna el estado de entrada en el recinto, modifica el valor almacenado o exige nonces criptográficos antirréplica.

Modal de creación de configuración de escáner
Modal de creación de configuración de escáner

Importante: Las reglas de validación se ejecutan de forma atómica en el servidor. Cuando un escaneo modifica el estado del pase (como VOIDED_AFTER_SCAN o StoredValueOperation.SUBTRACT), las solicitudes concurrentes duplicadas se serializan mediante bloqueos de idempotencia (x-idempotency-key) para evitar condiciones de carrera entre múltiples cajas.

Enumeraciones de configuración y resultado

Al configurar perfiles de validación en Escáner -> Configuraciones de escáner (/scanner/configs) o mediante /api/v1/validation/configs, cinco enumeraciones de Passinstance database controlan el comportamiento del terminal y los resultados persistidos del escaneo:

1. Enumeración ScanMode

Valor ScanModeComportamiento y transición de estadoCaso de uso habitual
SAVE_ATTENDANCERegistra un evento de escaneo válido y ejecuta las mecánicas de fidelización o sellos vinculadas sin anular el pase.Tarjetas de fidelización multivisita, abonos de gimnasio, pases de temporada.
VOIDED_AFTER_SCANCambia de forma atómica el estado del pase a VOIDED en el primer escaneo válido; los escaneos posteriores devuelven ALREADY_VOIDED.Cupones de un solo uso, vales promocionales, entradas de un único acceso.
INVALIDATE_AFTER_SCANMarca el pase como invalidado tras el canje y bloquea futuras aceptaciones bajo la configuración de validación.Pases de un único canje y vales de invitado restringidos.
CHECK_INCambia el estado de asistencia del pase a registrado (checked-in); rechaza nuevos registros si ya está dentro.Acceso a sesiones de congresos, puertas de control de acceso.
CHECK_OUTCambia el estado de asistencia del pase de registrado a salida completada (checked-out).Control de salidas del recinto, gestión de aforo.
CHECK_IN_CHECK_OUT_TOGGLEAlterna automáticamente entre CHECK_IN y CHECK_OUT en escaneos sucesivos.Espacios de coworking, pulseras o pases para festivales de varios días.

2. Enumeraciones de valor almacenado, NFC y resultado de escaneo

Tipo de enumeraciónValores permitidosFinalidad
StoredValueOperationNONE, ADD, SUBTRACT, SETDefine si un escaneo mantiene intacto el saldo, recarga crédito (ADD), debita el importe de compra (SUBTRACT) o sobrescribe el saldo (SET).
StoredValueAmountSourceFIXED, OPERATOR, MECHANICDetermina si el importe de la transacción proviene de un valor predefinido en la configuración (FIXED), de la entrada del cajero (OPERATOR) o de la mecánica de la plantilla (MECHANIC).
NfcReaderModeAUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAPConfigura la negociación del protocolo del lector sin contacto para terminales Apple VAS y Google Smart Tap.
scan actionINCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOPAcción registrada en cada uso del pase o transacción del libro mayor de escaneos (request payload también permite SET).
scan statusSUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUTEstado granular persistido en el registro de auditoría Scan (incluyendo transiciones explícitas de entrada y salida).

Canalización de 14 reglas de Validation Rules Engine

Cuando POST /api/v1/scans recibe una carga útil, Validation Rules Engine ejecuta 14 reglas de validación priorizadas en cuatro etapas (Core -> Mechanics -> Security -> Fallback):

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
CANALIZACIÓN DE 14 REGLAS DE VALIDACIÓN DE NEGOCIO
ETAPA 01 POST/api/v1/scans (request payload + x-scanner-key)
ETAPA 02 Etapa 1: Reglas básicas (Core Rules)
1
PassStatusRuleVerifica que el pase esté ACTIVE (no VOIDED / SUSPENDED)
2
ExpirationRuleVerifica now() < expirationDate
3
TimeWindowRuleVerifica que el escaneo esté dentro del horario permitido
4
GeofencingRuleVerifica coordenadas GPS {lat, lng} dentro del radio
ETAPA 03 Etapa 2: Reglas de mecánicas (Mechanics Rules)
5
OncePerDayRuleRechaza si el pase ya fue escaneado en la ventana móvil
6
StampCardAddRuleIncrementa contador de sellos y evalúa hito
7
StampCardDeductRuleDeduce sellos al canjear recompensa
8
PrepaidCardRuleEjecuta ADD / SUBTRACT / SET sobre valor almacenado
9
LoyaltyProgramRuleCalcula y aplica pointsDelta
10
TierEvaluationRuleAsciende el nivel del pase si supera el umbral
ETAPA 04 Etapa 3: Reglas de seguridad (Security Rules)
11
RateLimitRuleEvita ráfagas rápidas de escaneo en un mismo pase
12
AntiReplayRuleVerifica scan nonce criptográfico de /scans/prepare
13
DeviceValidationRuleVerifica clave del escáner y vinculación del terminal
ETAPA 05 Etapa 4: Respaldo (Fallback)
14
DefaultAcceptanceRuleEmite decision: "SUCCESS", status: "ACCEPTED"

Cada regla evaluada durante un escaneo añade su resultado de ejecución al arreglo ruleTrace en request payload, proporcionando una traza diagnóstica completa.

Nonces antirréplica (POST /api/v1/scans/prepare)

Para proteger entradas de alto valor y vales frente a capturas de pantalla estáticas del código de barras, los terminales pueden solicitar un scan nonce criptográfico de corta duración antes de la ejecución final:

Solicitud

POST /api/v1/scans/prepare
Encabezado
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "scannedBarcodeValue": "PI-TKT-992014",
  "scannerConfigurationId": "scfg_main_entrance_01"
}

Respuesta (201 Created)

JSON
{
  "success": true,
  "data": {
    "nonce": "snonce_8841a9c2f01e4b72",
    "expiresAt": "2026-11-15T22:35:30.000Z"
  }
}

Al pasar "nonce": "snonce_8841a9c2f01e4b72" dentro de la carga útil posterior de POST /api/v1/scans, se cumple AntiReplayRule y se consume el nonce inmediatamente para impedir su reutilización.

Esquema de ejecución de escaneo (POST /api/v1/scans)

Carga útil request payload

JSON
{
  "scannedBarcodeValue": "PI-LOY-449102",
  "scannerConfigurationId": "scfg_register_01",
  "nonce": "snonce_8841a9c2f01e4b72",
  "timestamp": "2026-11-15T22:35:10.000Z",
  "location": {
    "lat": 52.520008,
    "lng": 13.404954
  },
  "channel": "NFC",
  "protocol": "VAS",
  "validationData": {
    "amount": 18.50,
    "place": "Flagship Berlin Store"
  },
  "operatorId": "emp_cashier_07",
  "terminalId": "pos_term_berlin_02",
  "configurationVersion": 4
}

Carga útil request payload y códigos de decisión

El motor devuelve uno de los siete valores canónicos de decision: SUCCESS, FAILED, ALREADY_USED, ALREADY_VOIDED, EXPIRED, INVALID o PENDING (cuando se requiere entrada del operador mediante scanForm).

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "reasonCode": "RULE_ACCEPTED",
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true },
    { "rule": "ExpirationRule", "passed": true },
    { "rule": "LoyaltyProgramRule", "passed": true, "pointsDelta": 185 },
    { "rule": "TierEvaluationRule", "passed": true, "upgradedTo": "GOLD" }
  ],
  "passSnapshot": {
    "id": "pass_loy_449102",
    "templateId": "tmpl_loyalty_01",
    "serialNumber": "PI-LOY-449102",
    "externalId": "crm_cust_44910",
    "status": "ACTIVE",
    "tier": "GOLD",
    "barcodeValue": "PI-LOY-449102",
    "storedValue": "42.00"
  },
  "remainingBalance": "42.00",
  "effects": {
    "oldBalance": "42.00",
    "newBalance": "42.00",
    "pointsDelta": 185,
    "transactionAmount": 18.50,
    "currency": "EUR"
  },
  "display": {
    "title": "Scan Accepted — Gold Tier!",
    "subtitle": "+185 Points awarded",
    "color": "success"
  },
  "configurationVersion": 4,
  "configurationStale": false
}

Para auditar escaneos completados y exportar registros en CSV, consulte Historial y resultados de escaneo.

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