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

Configuración del escáner

Define lugares de validación, crea perfiles de escáner (App móvil o Web Scanner) e instala la app oficial.

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 ampliado1 / 2
Elementos clave de la interfaz

Asistente «Crear configuración de escáner» (Zoom)

Define el nombre de la configuración, la descripción, el tipo Mobile App y la duración del mensaje de éxito para generar un perfil de escáner seguro.

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

Controles de lugares de validación y configuración del escáner
Controles de lugares de validación y configuración del escáner

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:manage o scans:read para 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)CanalMecanismo de autenticaciónDespliegue habitual
SMART_SCAN_APPAplicación Passinstance Scanner (iOS / Android) y SDK integrados en POSClave emparejada x-scanner-key (from-link o for-config)Dispositivos portátiles de control de acceso, recintos sin conexión, cajas registradoras.
VALIDATION_LINKPunto de control en navegador web (/api/v1/public/validation/:configId/validate)Enlace web de validación firmadoMostradores temporales de eventos o puestos de socios sin instalación de aplicación.

Configuración paso a paso

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

  1. 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 hasta MAX_RETRY_ATTEMPTS = 3 con encabezados x-idempotency-key generados en el cliente y almacena en caché instantáneas de pases mediante GET /api/v1/scans/offline-dataset.

Arquitectura y ciclo de vida del emparejamiento de dispositivos

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
EMPAREJAMIENTO DE ESCÁNER Y SINCRONIZACIÓN DE TELEMETRÍA
ACTORES DEL SISTEMA
P1 Dispositivo / App escáner
P2 Scanner Keys API
P3 Scan Validation API
PASO 1 SOLICITUD / ACCIÓN POST/scanner-keys/
›
from-link {token, pin?}
PASO 2 RESPUESTA 201 Created
›
{ scannerKey,
›
alidationConfig,
›
key: "sk_live_..." }
PASO 3 SOLICITUD / ACCIÓN GET/scanner-keys/verify
›
Headers: x-scanner-key,
›
x-scanner-battery-level,
›
x-scanner-queue-backlog
PASO 4 RESPUESTA 200 OK { shouldRotate }
PASO 5 SOLICITUD / ACCIÓN GET/scans/offline-dataset ?cursor=...&limit=500
PASO 6 RESPUESTA 200 OK { items, nextCursor, snapshotAt }

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étodoEndpointAutenticación / GuardiaDescripción
POST/api/v1/scanner-keys/from-linkPú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-configJWT del espacio de trabajo (scans:read)Emite una nueva clave de escáner para un { configId } perteneciente al inquilino.
GET/api/v1/scanner-keys/configsx-scanner-keyLista las configuraciones activas SMART_SCAN_APP vinculadas al inquilino de la clave solicitante.
POST/api/v1/scanner-keys/switchx-scanner-keyCambia la clave a otro { configId, pin? } cuando allowChangesViaLink: true.
POST/api/v1/scanner-keys/unlock-pinx-scanner-keyVerifica { pin } frente a unlockPinHash con protección automática frente a fuerza bruta.
GET/api/v1/scanner-keys/verifyx-scanner-keyValida el estado de la clave, registra encabezados de telemetría del dispositivo y devuelve la recomendación shouldRotate.
POST/api/v1/scanner-keys/revokex-scanner-keyRevoca inmediatamente la clave de escáner solicitante, bloqueando todos los envíos de escaneo posteriores.
POST/api/v1/scanner-keys/:id/rotateJWT 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:

JSON
{
  "token": "sal_9f82b1c4e7a043d19b2e",
  "pin": "4829"
}

Respuesta (201 Created):

JSON
{
  "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 key se 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. Guarde key de forma segura en el llavero del dispositivo; si se pierde, invoque POST /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íaFormato / EjemploFinalidad
x-scanner-app-version2.4.1 (build 108)Registra la versión de compilación de la aplicación en los dispositivos desplegados.
x-scanner-device-idios-idfv-8841-992aIdentificador único de hardware para el inventario de la flota de dispositivos.
x-scanner-battery-level0.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-backlog12Número de escaneos sin conexión en cola local pendientes de sincronización.

Respuesta (200 OK):

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

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

GET /api/v1/scans/offline-dataset?limit=500&snapshotAt=2026-11-16T08:00:00.000Z
Encabezado
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "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.

Documentación de producto y API 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.