Skip to content
Guia da Central de Ajuda · Leitura de passesFase de integração 4
6 min de leituraVerificado 2026-11-16

Instalação e configuração do Scanner

Crie Locais de Validação, configure perfis de Scanner (App móvel ou Web Scanner) e instale a app oficial.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface1 / 2
Elementos-chave da interface

Assistente «Criar configuração de Scanner» (Zoom)

Defina o nome da configuração, a descrição, o tipo Mobile App e a duração da mensagem de sucesso para gerar um perfil de leitura seguro.

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

Locais de validação do scanner e controlos de configuração
Locais de validação do scanner e controlos de configuração

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, ou scans:read para 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)CanalMecanismo de AutenticaçãoImplementação Típica
SMART_SCAN_APPAplicação Passinstance Scanner (iOS / Android) e SDKs POS integradosx-scanner-key emparelhada (from-link ou for-config)Leitores portáteis de controlo de acessos, recintos offline, caixas de retalho.
VALIDATION_LINKPonto de verificação em navegador web (/api/v1/public/validation/:configId/validate)Ligação web de validação assinadaBalcões temporários de eventos ou stands de parceiros sem instalação de aplicação.

Configuração Passo a Passo

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

  1. 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 = 3 com cabeçalhos x-idempotency-key gerados no cliente e coloca instantâneos de passes em cache através de GET /api/v1/scans/offline-dataset.

Arquitetura e Ciclo de Vida do Emparelhamento de Dispositivos

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
FLUXO DA ARQUITETURA DO SISTEMA: EMPARELHAMENTO DO SCANNER E SINCRONIZAÇÃO DE TELEMETRIA
ATORES DE SISTEMA PARTICIPANTES
P1 Dispositivo / App Scanner
P2 Scanner Keys API
P3 Scan Validation API
ETAPA 1 PEDIDO / AÇÃO POST/scanner-keys/
›
from-link {token, pin?}
ETAPA 2 RESPOSTA 201 Created
›
{ scannerKey,
›
alidationConfig,
›
key: "sk_live_..." }
ETAPA 3 PEDIDO / AÇÃO GET/scanner-keys/verify
›
Headers: x-scanner-key,
›
x-scanner-battery-level,
›
x-scanner-queue-backlog
ETAPA 4 RESPOSTA 200 OK { shouldRotate }
ETAPA 5 PEDIDO / AÇÃO GET/scans/offline-dataset ?cursor=...&limit=500
ETAPA 6 RESPOSTA 200 OK { items, nextCursor, snapshotAt }

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étodoEndpointAuth / GuardDescrição
POST/api/v1/scanner-keys/from-linkPú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-configJWT do Espaço de Trabalho (scans:read)Emite uma nova chave de scanner para um { configId } pertencente ao inquilino.
GET/api/v1/scanner-keys/configsx-scanner-keyLista configurações SMART_SCAN_APP ativas associadas ao inquilino da chave invocante.
POST/api/v1/scanner-keys/switchx-scanner-keyMuda a chave para outro { configId, pin? } quando allowChangesViaLink: true.
POST/api/v1/scanner-keys/unlock-pinx-scanner-keyVerifica { pin } face a unlockPinHash com proteção automática contra bloqueio por força bruta.
GET/api/v1/scanner-keys/verifyx-scanner-keyValida o estado da chave, regista cabeçalhos de telemetria do dispositivo e devolve o aviso shouldRotate.
POST/api/v1/scanner-keys/revokex-scanner-keyRevoga imediatamente a chave do scanner invocante, bloqueando todos os envios de leitura subsequentes.
POST/api/v1/scanner-keys/:id/rotateJWT 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:

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

Resposta (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: 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. Guarde key em segurança no porta-chaves do dispositivo; em caso de perda, invoque POST /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 TelemetriaFormato / ExemploFinalidade
x-scanner-app-version2.4.1 (build 108)Acompanha a versão de compilação da aplicação nos dispositivos portáteis implementados.
x-scanner-device-idios-idfv-8841-992aIdentificador único de hardware para inventário da frota de dispositivos.
x-scanner-battery-level0.78 (0–1 ou 0–100)Alerta os operadores quando os scanners de porta descem abaixo de 15% de bateria.
x-scanner-queue-backlog12Número de leituras offline em fila local a aguardar sincronização de carregamento.

Resposta (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."
}

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:

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

GET /api/v1/scans/offline-dataset?limit=500&snapshotAt=2026-11-16T08:00:00.000Z
Cabeçalho
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 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.

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.