Visão geral
Antes que operadores de caixa, assistentes de entrada ou terminais POS de retalho possam validar passes de carteira dos clientes, tem de configurar um Local de Validação e associar uma Configuração de Scanner (modelo ScannerConfiguration) no seu espaço de trabalho (/scanner e /scanner/configs no Painel). A Passinstance gere o emparelhamento de dispositivos, a imposição de PIN do operador, a rotação de chaves, o reporte de telemetria e a sincronização de instantâneos offline através de Scanner Keys API (/api/v1/scanner-keys), Validation Config API (/api/v1/validation) e Scan Validation API (/api/v1/scans).

Pré-requisitos: Tem de possuir um Modelo de Passe publicado ativo e permissões no espaço de trabalho para gerir configurações de validação (
validation:manage, ouscans:readpara aprovisionamento de chaves) antes de gerar ligações de emparelhamento ou aprovisionar chaves de scanner em bruto.
Tipos de Configuração de Scanner e Enums Principais
A Passinstance separa a leitura nativa em dispositivos portáteis das ligações públicas baseadas em navegador através de ScannerConfigurationType:
Enum (ScannerConfigurationType) | Canal | Mecanismo de Autenticação | Implementação Típica |
|---|---|---|---|
SMART_SCAN_APP | Aplicação Passinstance Scanner (iOS / Android) e SDKs POS integrados | x-scanner-key emparelhada (from-link ou for-config) | Leitores portáteis de controlo de acessos, recintos offline, caixas de retalho. |
VALIDATION_LINK | Ponto de verificação em navegador web (/api/v1/public/validation/:configId/validate) | Ligação web de validação assinada | Balcões temporários de eventos ou stands de parceiros sem instalação de aplicação. |
Configuração Passo a Passo
-
1
Definir Locais de Validação: Crie pontos de verificação físicos ou lógicos (por exemplo, Entrada Principal, Caixa 1, Sala VIP) para segmentar as análises de leitura e restringir onde cada passe pode ser resgatado (
validValidationPlaces). -
2
Criar uma Configuração de Scanner: Em Scanner -> Configurações de Scanner (
/scanner/configs), defina o nome do perfil,type(ScannerConfigurationType), modelos permitidos (templateId/allowedTemplates),ScanMode,StoredValueOperation(NONE | ADD | SUBTRACT | SET),StoredValueAmountSource(FIXED | OPERATOR | MECHANIC), PIN do operador (unlockPinHash) e se a equipa pode trocar de perfil em funcionamento (allowChangesViaLink: true). -
3
Emparelhar o Dispositivo ou Aprovisionar uma Chave:
- Aplicação Móvel (SMART_SCAN_APP): Leia um código QR de ligação de emparelhamento (ScannerAccessLink) ou introduza um token de acesso para o trocar através de POST /api/v1/scanner-keys/from-link. - Aplicação Autenticada / Terminal POS: Após iniciar sessão e selecionar o perfil, emita uma chave dedicada diretamente através de POST /api/v1/scanner-keys/for-config.
-
4
Verificar Heartbeat e Sincronização Offline: A aplicação scanner verifica a integridade da chave através de
GET /api/v1/scanner-keys/verify, coloca em fila envios offline falhados atéMAX_RETRY_ATTEMPTS = 3com cabeçalhosx-idempotency-keygerados no cliente e coloca instantâneos de passes em cache através deGET /api/v1/scans/offline-dataset.
Arquitetura e Ciclo de Vida do Emparelhamento de Dispositivos
Endpoints do Ciclo de Vida das Chaves de Scanner (Scanner Keys API)
Todas as operações de aprovisionamento de chaves de dispositivo, troca de perfil, verificação de PIN e rotação estão expostas sob /api/v1/scanner-keys:
| Método | Endpoint | Auth / Guard | Descrição |
|---|---|---|---|
| POST | /api/v1/scanner-keys/from-link | Público (ScannerAccessLink, isento de CSRF) | Troca { token, pin? } por uma x-scanner-key persistente (key, devolvida uma única vez). |
| POST | /api/v1/scanner-keys/for-config | JWT do Espaço de Trabalho (scans:read) | Emite uma nova chave de scanner para um { configId } pertencente ao inquilino. |
| GET | /api/v1/scanner-keys/configs | x-scanner-key | Lista configurações SMART_SCAN_APP ativas associadas ao inquilino da chave invocante. |
| POST | /api/v1/scanner-keys/switch | x-scanner-key | Muda a chave para outro { configId, pin? } quando allowChangesViaLink: true. |
| POST | /api/v1/scanner-keys/unlock-pin | x-scanner-key | Verifica { pin } face a unlockPinHash com proteção automática contra bloqueio por força bruta. |
| GET | /api/v1/scanner-keys/verify | x-scanner-key | Valida o estado da chave, regista cabeçalhos de telemetria do dispositivo e devolve o aviso shouldRotate. |
| POST | /api/v1/scanner-keys/revoke | x-scanner-key | Revoga imediatamente a chave do scanner invocante, bloqueando todos os envios de leitura subsequentes. |
| POST | /api/v1/scanner-keys/:id/rotate | JWT do Espaço de Trabalho (scans:read) | Roda atomicamente uma chave de scanner existente por ID e devolve uma nova chave secreta em bruto uma única vez. |
1. Emparelhamento por Ligação de Acesso (POST /api/v1/scanner-keys/from-link)
Quando a equipa lê um código QR de configuração na aplicação Passinstance Scanner, o dispositivo troca o token de configuração (e o PIN opcional do operador caso unlockPinHash esteja configurado) por uma x-scanner-key persistente:
{
"token": "sal_9f82b1c4e7a043d19b2e",
"pin": "4829"
}
Resposta (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: O valor
keyé devolvido apenas uma vez no momento da criação ou rotação e armazenado como hash SHA-256 (hashKey) na base de dados. Guardekeyem segurança no porta-chaves do dispositivo; em caso de perda, invoquePOST /api/v1/scanner-keys/:id/rotate.
2. Heartbeat, Telemetria e Aviso de Rotação (GET /api/v1/scanner-keys/verify)
Os clientes de scanner chamam periodicamente GET /api/v1/scanner-keys/verify com x-scanner-key e cabeçalhos operacionais de telemetria para que os administradores possam monitorizar a integridade da frota de dispositivos em tempo real:
| Cabeçalho de Telemetria | Formato / Exemplo | Finalidade |
|---|---|---|
x-scanner-app-version | 2.4.1 (build 108) | Acompanha a versão de compilação da aplicação nos dispositivos portáteis implementados. |
x-scanner-device-id | ios-idfv-8841-992a | Identificador único de hardware para inventário da frota de dispositivos. |
x-scanner-battery-level | 0.78 (0–1 ou 0–100) | Alerta os operadores quando os scanners de porta descem abaixo de 15% de bateria. |
x-scanner-queue-backlog | 12 | Número de leituras offline em fila local a aguardar sincronização de carregamento. |
Resposta (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."
}
Quando daysUntilExpiration < 15, shouldRotate passa a true, solicitando ao dispositivo ou administrador que rode a credencial através de POST /api/v1/scanner-keys/:id/rotate.
3. Mudança de Perfil em Funcionamento (POST /api/v1/scanner-keys/switch)
Se uma configuração tiver allowChangesViaLink: true, os operadores podem alternar um único scanner portátil entre diferentes perfis SMART_SCAN_APP (por exemplo, passar de Check-in na Entrada para Resgate de Merchandising VIP) sem voltar a emparelhar:
{
"configId": "scfg_vip_merch_02",
"pin": "9012"
}
Se a configuração de destino exigir um PIN do operador, o servidor valida pin face a unlockPinHash antes de reassociar a chave. Os operadores também podem validar o PIN de forma autónoma através de POST /api/v1/scanner-keys/unlock-pin.
Sincronização de Conjunto de Dados Offline (GET /api/v1/scans/offline-dataset)
Para recintos com conectividade móvel ou Wi-Fi intermitente, os scanners móveis sincronizam um instantâneo compacto de passes no âmbito da chave (offline scan dataset) através de GET /api/v1/scans/offline-dataset.
Parâmetros de Consulta
-
cursor(string opcional): Cursor de paginação devolvido pela página anterior (nextCursor). -
limit(number opcional): Máximo de registos por página. -
snapshotAt(carimbo temporal ISO 8601 opcional): Carimbo temporal de sincronização delta incremental para obter apenas passes criados, atualizados ou anulados desde o último instantâneo.
Exemplo de Pedido e Item de Passe em Instantâneo (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 a compatibilidade de hardware e os fluxos de trabalho de validação na Página do Produto Scanner e em Modos de Leitura e Regras de Validação.
