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.

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_SCANoStoredValueOperation.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 ScanMode | Comportamiento y transición de estado | Caso de uso habitual |
|---|---|---|
SAVE_ATTENDANCE | Registra 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_SCAN | Cambia 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_SCAN | Marca 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_IN | Cambia 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_OUT | Cambia 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_TOGGLE | Alterna 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ón | Valores permitidos | Finalidad |
|---|---|---|
StoredValueOperation | NONE, ADD, SUBTRACT, SET | Define si un escaneo mantiene intacto el saldo, recarga crédito (ADD), debita el importe de compra (SUBTRACT) o sobrescribe el saldo (SET). |
StoredValueAmountSource | FIXED, OPERATOR, MECHANIC | Determina 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). |
NfcReaderMode | AUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAP | Configura la negociación del protocolo del lector sin contacto para terminales Apple VAS y Google Smart Tap. |
| scan action | INCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOP | Acción registrada en cada uso del pase o transacción del libro mayor de escaneos (request payload también permite SET). |
| scan status | SUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT | Estado 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):
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
/api/v1/scans/prepare
{
"scannedBarcodeValue": "PI-TKT-992014",
"scannerConfigurationId": "scfg_main_entrance_01"
}
Respuesta (201 Created)
{
"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
{
"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).
{
"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.
