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.

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_SCANouStoredValueOperation.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 ScanMode | Comportamento e Transição de Estado | Caso de Utilização Típico |
|---|---|---|
SAVE_ATTENDANCE | Regista 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_SCAN | Transita 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_SCAN | Marca 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_IN | Transita 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_OUT | Transita 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_TOGGLE | Alterna 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 Enum | Valores Permitidos | Finalidade |
|---|---|---|
StoredValueOperation | NONE, ADD, SUBTRACT, SET | Define se uma leitura deixa os saldos inalterados, adiciona crédito (ADD), debita o valor da compra (SUBTRACT) ou substitui o saldo (SET). |
StoredValueAmountSource | FIXED, OPERATOR, MECHANIC | Determina 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). |
NfcReaderMode | AUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAP | Configura a negociação de protocolo de leitores sem contacto para terminais Apple VAS e Google Smart Tap. |
| scan action | INCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOP | Ação registada em cada utilização de passe ou transação no razão de leitura (request payload também permite SET). |
| scan status | SUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT | Estado 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):
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
/api/v1/scans/prepare
{
"scannedBarcodeValue": "PI-TKT-992014",
"scannerConfigurationId": "scfg_main_entrance_01"
}
Resposta (201 Created)
{
"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
{
"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).
{
"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.
