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

Modos de leitura e regras de validação

Configure resgate único, check-in/out, limite diário, mensagens ao operador e comportamento offline.

Neste guia

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

Foco ampliado da interface
Elementos-chave da interface

Mensagem pós-leitura e configurações de Scanner (Zoom)

Personalize a mensagem de confirmação do operador utilizando marcadores como {holderName} e gira as ligações de acesso ativas.

Visão geral

Cada leitura enviada para POST /api/v1/scans é avaliada face à ScannerConfiguration ativa (resolvida a partir da x-scanner-key associada ou de scannerConfigurationId / validationConfigId em request payload) e a um pipeline determinístico de 14 regras do Validation Rules Engine. Em conjunto, estas definições determinam se um passe regista presenças, fica anulado após uma única utilização, alterna o estado de check-in no recinto, altera o saldo pré-pago ou impõe nonces criptográficos anti-repetição.

Modal de criação de configuração de scanner
Modal de criação de configuração de scanner

Importante: As regras de validação são executadas de forma atómica no servidor. Quando uma leitura altera o estado do passe (como VOIDED_AFTER_SCAN ou StoredValueOperation.SUBTRACT), pedidos concorrentes duplicados são serializados usando bloqueios de idempotência (x-idempotency-key) para evitar condições de corrida entre múltiplas caixas.

Enumerações de Configuração e Resultados

Ao configurar perfis de validação em Scanner -> Configurações de Scanner (/scanner/configs) ou através de /api/v1/validation/configs, cinco enumerações Passinstance database controlam o comportamento do terminal e os resultados persistidos da leitura:

1. Enum ScanMode

Valor ScanModeComportamento e Transição de EstadoCaso de Utilização Típico
SAVE_ATTENDANCERegista um evento de leitura válido e executa mecânicas associadas de fidelização/carimbos sem anular o passe.Cartões de fidelização multivisitantes, mensalidades de ginásio, passes sazonais.
VOIDED_AFTER_SCANTransita atomicamente o estado do passe para VOIDED na primeira leitura válida; leituras subsequentes devolvem ALREADY_VOIDED.Cupões de utilização única, vales promocionais, bilhetes de entrada única.
INVALIDATE_AFTER_SCANMarca o passe como invalidado após o resgate e bloqueia a aceitação futura sob a configuração de validação.Passes de resgate único e vales de convidado restritos.
CHECK_INTransita o estado de presença do passe para com check-in efetuado; rejeita novos check-ins caso já esteja no interior.Entrada em sessões de conferência, portões de acesso controlado.
CHECK_OUTTransita o estado de presença do passe de check-in efetuado para check-out efetuado.Controlo de saída do recinto, gestão de lotação.
CHECK_IN_CHECK_OUT_TOGGLEAlterna automaticamente entre CHECK_IN e CHECK_OUT em leituras sucessivas.Espaços de coworking, pulseiras/passes de festivais de vários dias.

2. Enumerações de Valor Armazenado, NFC e Resultados da Leitura

Tipo de EnumValores PermitidosFinalidade
StoredValueOperationNONE, ADD, SUBTRACT, SETDefine se uma leitura deixa os saldos inalterados, adiciona crédito (ADD), debita o valor da compra (SUBTRACT) ou substitui o saldo (SET).
StoredValueAmountSourceFIXED, OPERATOR, MECHANICDetermina se o montante da transação provém de um valor predefinido na configuração (FIXED), pedido ao operador de caixa (OPERATOR) ou mecânica do modelo (MECHANIC).
NfcReaderModeAUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAPConfigura a negociação de protocolo de leitores sem contacto para terminais Apple VAS e Google Smart Tap.
scan actionINCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOPAção registada em cada utilização de passe ou transação no razão de leitura (request payload também permite SET).
scan statusSUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUTEstado granular persistido no registo de auditoria Scan (incluindo transições explícitas de check-in/check-out).

O Pipeline de 14 Regras do Validation Rules Engine

Quando POST /api/v1/scans recebe um payload, o Validation Rules Engine executa 14 regras de validação priorizadas em quatro fases (Core -> Mechanics -> Security -> Fallback):

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
FLUXO DA ARQUITETURA DO SISTEMA: PIPELINE DE 14 REGRAS DE VALIDAÇÃO
ETAPA 01 POST/api/v1/scans (request payload + x-scanner-key)
ETAPA 02 Fase 1: Regras Base
1
PassStatusRuleVerifica se o passe está ACTIVE (não VOIDED / SUSPENDED)
2
ExpirationRuleVerifica now() < expirationDate
3
TimeWindowRuleVerifica se a leitura ocorre no horário permitido
4
GeofencingRuleVerifica se GPS {lat, lng} está dentro do raio
ETAPA 03 Fase 2: Regras de Mecânicas
5
OncePerDayRuleRejeita se já foi lido na janela móvel diária
6
StampCardAddRuleIncrementa contador de carimbos e avalia marco
7
StampCardDeductRuleDeduz carimbos para resgate de recompensa
8
PrepaidCardRuleExecuta ADD / SUBTRACT / SET no saldo pré-pago
9
LoyaltyProgramRuleCalcula e aplica pointsDelta
10
TierEvaluationRulePromove o patamar se o limiar for ultrapassado
ETAPA 04 Fase 3: Regras de Segurança
11
RateLimitRuleEvita enxurrada rápida de leituras no mesmo passe
12
AntiReplayRuleValida o scan nonce criptográfico de /scans/prepare
13
DeviceValidationRuleValida a chave do scanner e vinculação ao terminal
ETAPA 05 Fase 4: Contingência
14
DefaultAcceptanceRuleEmite decision: "SUCCESS", status: "ACCEPTED"

Cada regra avaliada durante uma leitura anexa o seu resultado de execução ao array ruleTrace em request payload, fornecendo um rasto de diagnóstico completo.

Nonces Anti-Repetição (POST /api/v1/scans/prepare)

Para proteger bilhetes e vales de elevado valor contra capturas de ecrã estáticas do código de barras, os terminais podem solicitar um scan nonce criptográfico de curta duração antes da execução final:

Pedido

POST /api/v1/scans/prepare
Cabeçalho
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "scannedBarcodeValue": "PI-TKT-992014",
  "scannerConfigurationId": "scfg_main_entrance_01"
}

Resposta (201 Created)

JSON
{
  "success": true,
  "data": {
    "nonce": "snonce_8841a9c2f01e4b72",
    "expiresAt": "2026-11-15T22:35:30.000Z"
  }
}

Enviar "nonce": "snonce_8841a9c2f01e4b72" no payload subsequente de POST /api/v1/scans satisfaz AntiReplayRule e invalida imediatamente o nonce para que não possa ser reutilizado.

Esquema de Execução de Leitura (POST /api/v1/scans)

Payload request payload

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

Payload request payload e Códigos de Decisão

O motor devolve um de sete valores canónicos de decision: SUCCESS, FAILED, ALREADY_USED, ALREADY_VOIDED, EXPIRED, INVALID, ou PENDING (quando é necessária introdução do operador através de scanForm).

JSON
{
  "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 leituras concluídas e exportar registos CSV, consulte Histórico e Resultados de Leituras.

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.