Descripción general
Antes de que cajeros, personal de acceso o terminales POS puedan validar los pases Wallet de sus clientes, debe configurar un lugar de validación (Validation Place) y asociar una configuración de escáner (modelo ScannerConfiguration) dentro de su espacio de trabajo (/scanner y /scanner/configs en el Panel de control). Passinstance gestiona el emparejamiento de dispositivos, el uso de PIN de operador, la rotación de claves, el reporte de telemetría y la sincronización de instantáneas sin conexión mediante Scanner Keys API (/api/v1/scanner-keys), Validation Config API (/api/v1/validation) y Scan Validation API (/api/v1/scans).

Requisitos previos: Debe contar con una plantilla de pase activa y publicada, así como con permisos del espacio de trabajo para gestionar configuraciones de validación (
validation:manageoscans:readpara aprovisionamiento de claves), antes de generar enlaces de emparejamiento o emitir claves de escáner directas.
Tipos de configuración de escáner y enumeraciones principales
Passinstance separa el escaneo mediante aplicaciones nativas en dispositivos móviles de los puntos de control públicos basados en navegador mediante ScannerConfigurationType:
Enumeración (ScannerConfigurationType) | Canal | Mecanismo de autenticación | Despliegue habitual |
|---|---|---|---|
SMART_SCAN_APP | Aplicación Passinstance Scanner (iOS / Android) y SDK integrados en POS | Clave emparejada x-scanner-key (from-link o for-config) | Dispositivos portátiles de control de acceso, recintos sin conexión, cajas registradoras. |
VALIDATION_LINK | Punto de control en navegador web (/api/v1/public/validation/:configId/validate) | Enlace web de validación firmado | Mostradores temporales de eventos o puestos de socios sin instalación de aplicación. |
Configuración paso a paso
-
1
Defina los lugares de validación: Cree puntos de control físicos o lógicos (por ejemplo, Entrada principal, Caja 1, Sala VIP) para segmentar la analítica de escaneos y restringir qué pases pueden canjearse en cada ubicación (
validValidationPlaces). -
2
Cree una configuración de escáner: En Escáner -> Configuraciones de escáner (
/scanner/configs), defina el nombre del perfil,type(ScannerConfigurationType), las plantillas permitidas (templateId/allowedTemplates),ScanMode,StoredValueOperation(NONE | ADD | SUBTRACT | SET),StoredValueAmountSource(FIXED | OPERATOR | MECHANIC), el PIN de operador (unlockPinHash) y si el personal puede cambiar de perfil sobre la marcha (allowChangesViaLink: true). -
3
Empareje el dispositivo o aprovisione una clave:
- Aplicación móvil (SMART_SCAN_APP): Escanee un enlace QR de emparejamiento (ScannerAccessLink) o introduzca un token de acceso para intercambiarlo mediante POST /api/v1/scanner-keys/from-link. - Aplicación autenticada / Terminal POS: Tras el inicio de sesión del usuario y la selección de perfil, emita una clave dedicada directamente mediante POST /api/v1/scanner-keys/for-config.
-
4
Verifique el latido (heartbeat) y la sincronización sin conexión: La aplicación del escáner verifica el estado de la clave mediante
GET /api/v1/scanner-keys/verify, encola los envíos fallidos sin conexión hastaMAX_RETRY_ATTEMPTS = 3con encabezadosx-idempotency-keygenerados en el cliente y almacena en caché instantáneas de pases medianteGET /api/v1/scans/offline-dataset.
Arquitectura y ciclo de vida del emparejamiento de dispositivos
Endpoints del ciclo de vida de claves de escáner (Scanner Keys API)
Todas las operaciones de aprovisionamiento de claves de dispositivo, cambio de perfil, verificación de PIN y rotación están expuestas bajo /api/v1/scanner-keys:
| Método | Endpoint | Autenticación / Guardia | Descripción |
|---|---|---|---|
| POST | /api/v1/scanner-keys/from-link | Público (ScannerAccessLink, exento de CSRF) | Intercambia { token, pin? } por una x-scanner-key persistente (key, devuelta una sola vez). |
| POST | /api/v1/scanner-keys/for-config | JWT del espacio de trabajo (scans:read) | Emite una nueva clave de escáner para un { configId } perteneciente al inquilino. |
| GET | /api/v1/scanner-keys/configs | x-scanner-key | Lista las configuraciones activas SMART_SCAN_APP vinculadas al inquilino de la clave solicitante. |
| POST | /api/v1/scanner-keys/switch | x-scanner-key | Cambia la clave a otro { configId, pin? } cuando allowChangesViaLink: true. |
| POST | /api/v1/scanner-keys/unlock-pin | x-scanner-key | Verifica { pin } frente a unlockPinHash con protección automática frente a fuerza bruta. |
| GET | /api/v1/scanner-keys/verify | x-scanner-key | Valida el estado de la clave, registra encabezados de telemetría del dispositivo y devuelve la recomendación shouldRotate. |
| POST | /api/v1/scanner-keys/revoke | x-scanner-key | Revoca inmediatamente la clave de escáner solicitante, bloqueando todos los envíos de escaneo posteriores. |
| POST | /api/v1/scanner-keys/:id/rotate | JWT del espacio de trabajo (scans:read) | Rota de forma atómica una clave de escáner existente por ID y devuelve una nueva clave secreta sin formato una sola vez. |
1. Emparejamiento mediante enlace de acceso (POST /api/v1/scanner-keys/from-link)
Cuando el personal escanea un código QR de configuración en la aplicación Passinstance Scanner, el dispositivo intercambia el token de configuración (y el PIN opcional de operador si unlockPinHash está configurado) por una x-scanner-key persistente:
{
"token": "sal_9f82b1c4e7a043d19b2e",
"pin": "4829"
}
Respuesta (201 Created):
{
"scannerKey": {
"id": "skey_01hxyz8912ab",
"createdAt": "2026-11-16T09:00:00.000Z",
"expiresAt": "2027-02-15T00:00:00.000Z"
},
"validationConfig": {
"id": "scfg_main_entrance_01",
"configurationId": "MAIN_ENTRANCE",
"name": "Main Entrance Gate",
"scanMode": "CHECK_IN",
"type": "SMART_SCAN_APP",
"place": "Main Entrance",
"isActive": true,
"allowChangesViaLink": true,
"templateId": "tmpl_event_vip",
"allowedTemplateIds": ["tmpl_event_vip"],
"version": 3
},
"key": "sk_live_7d9a2f4b8c1e6039a5d2e8f1"
}
Importante: El valor
keyse devuelve una sola vez en el momento de creación o rotación y se almacena como un hash SHA-256 (hashKey) en la base de datos. Guardekeyde forma segura en el llavero del dispositivo; si se pierde, invoquePOST /api/v1/scanner-keys/:id/rotate.
2. Latido (heartbeat), telemetría y aviso de rotación (GET /api/v1/scanner-keys/verify)
Los clientes escáner llaman periódicamente a GET /api/v1/scanner-keys/verify con x-scanner-key y encabezados de telemetría operativa para que los administradores puedan supervisar la salud de la flota en tiempo real:
| Encabezado de telemetría | Formato / Ejemplo | Finalidad |
|---|---|---|
x-scanner-app-version | 2.4.1 (build 108) | Registra la versión de compilación de la aplicación en los dispositivos desplegados. |
x-scanner-device-id | ios-idfv-8841-992a | Identificador único de hardware para el inventario de la flota de dispositivos. |
x-scanner-battery-level | 0.78 (0–1 o 0–100) | Alerta al equipo de operaciones cuando la batería de los escáneres de puerta baja del 15 %. |
x-scanner-queue-backlog | 12 | Número de escaneos sin conexión en cola local pendientes de sincronización. |
Respuesta (200 OK):
{
"valid": true,
"scannerKeyId": "skey_01hxyz8912ab",
"scannerConfigurationId": "scfg_main_entrance_01",
"validationConfigId": "scfg_main_entrance_01",
"expiresAt": "2026-11-25T12:00:00.000Z",
"daysUntilExpiration": 9,
"shouldRotate": true,
"message": "Scanner key is approaching expiration. Please rotate soon."
}
Cuando daysUntilExpiration < 15, shouldRotate devuelve true, solicitando al dispositivo o al administrador que rote la credencial mediante POST /api/v1/scanner-keys/:id/rotate.
3. Cambio de perfil sobre la marcha (POST /api/v1/scanner-keys/switch)
Si una configuración tiene allowChangesViaLink: true, el personal puede alternar un único escáner portátil entre distintos perfiles SMART_SCAN_APP (por ejemplo, pasar de Registro de entrada a Canje de mercancía VIP) sin volver a emparejarlo:
{
"configId": "scfg_vip_merch_02",
"pin": "9012"
}
Si la configuración de destino exige un PIN de operador, el servidor valida pin frente a unlockPinHash antes de reasignar la clave. Los operadores también pueden validar su PIN de forma independiente mediante POST /api/v1/scanner-keys/unlock-pin.
Sincronización de conjuntos de datos sin conexión (GET /api/v1/scans/offline-dataset)
Para recintos con conectividad móvil o Wi-Fi intermitente, los escáneres móviles sincronizan una instantánea compacta de pases limitada a la clave (offline scan dataset) mediante GET /api/v1/scans/offline-dataset.
Parámetros de consulta
-
cursor(string opcional): Cursor de paginación devuelto por la página anterior (nextCursor). -
limit(number opcional): Número máximo de registros por página. -
snapshotAt(marca temporal ISO 8601 opcional): Marca de tiempo de sincronización incremental (delta) para obtener únicamente pases creados, actualizados o anulados desde la última instantánea.
Ejemplo de solicitud y elemento de instantánea de pase (IOfflineDatasetPassResponse)
/api/v1/scans/offline-dataset?limit=500&snapshotAt=2026-11-16T08:00:00.000Z
{
"config": {
"id": "scfg_main_entrance_01",
"customerTimezone": "Europe/Berlin",
"scanMode": "CHECK_IN",
"validValidationPlaces": ["Main Entrance"]
},
"snapshotAt": "2026-11-16T09:00:00.000Z",
"nextCursor": "pass_01hxyz9940",
"hasMore": true,
"items": [
{
"id": "pass_01hxyz9939",
"templateId": "tmpl_event_vip",
"serialNumber": "PI-VIP-00419",
"externalId": "crm_attendee_9012",
"barcodeValue": "PI-VIP-00419",
"status": "ACTIVE",
"voided": false,
"expirationDate": "2026-12-31T23:59:59.000Z",
"storedValue": "50.00",
"mechanicType": "NONE",
"lastSuccessfulScanAt": "2026-11-15T19:04:00.000Z",
"validationPlaces": ["Main Entrance"]
}
]
}
Explore la compatibilidad de hardware y los flujos de validación en la Página de producto del escáner y en Modos de escaneo y reglas de validación.
