Visão geral
Cada leitura de código de barras ou toque NFC sem contacto processado através da App Scanner Móvel, do Web Scanner, da Integração POS (POST /v1/pos/redeem e POST /v1/pos/scan), da Orquestração de Leitores Hardware (POST /api/v1/reader/redeem) ou da API de Execução de Leitura (POST /api/v1/scans) gera um registo de auditoria imutável e rastreável criptograficamente. Os Relatórios de Leitura e Resgate (/scanner no Painel e /api/v1/validation/scans) agregam estes eventos por configuração de scanner, local físico de validação, ID de operador e livros-razão de mecânicas para proporcionar visibilidade operacional completa.
Pipeline de Telemetria de Leitura e Rastreio de Regras
Importante: Cada resposta de leitura grava um array completo
ruleTracejuntamente comoperatorId,terminalId,scannerConfigurationId,externalIde coordenadas GPSlocation, permitindo às equipas de conformidade auditar exatamente por que razão uma leitura foi aceite ou rejeitada.
Definição de Métricas, scan status e Detalhe de PosOperation
O Passinstance classifica o tráfego de validação em métricas canónicas definidas em PASS_ANALYTICS_METRIC_DEFINITIONS, suportadas por decision in the scan response e pelo enum Passinstance database scan status (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT):
| Chave da Métrica | decision / scan status subjacente | Significado Operacional |
|---|---|---|
totalScans | Todos os eventos de leitura | Total de apresentações de código de barras ou NFC recebidas pelo motor de validação no período consultado. |
successfulScans | decision: 'SUCCESS' (SUCCESS, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS) | Leituras que passaram nas 14 regras de validação e executaram a ação de presença ou mecânica configurada (scan action). |
duplicateScans | decision: 'ALREADY_USED' ou 'ALREADY_VOIDED' (ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT) | Tentativas repetidas em cupões de utilização única (VOIDED_AFTER_SCAN scan mode) ou cartões já registados em entrada/saída. |
expiredScans | decision: 'EXPIRED' (EXPIRED) | Apresentação de cartões cuja expirationDate já terminou. |
rejectedScans | decision: 'INVALID' (INVALID) | Dados de código de barras desconhecidos, séries de outro inquilino ou assinaturas criptográficas NFC inválidas. |
failedScans | decision: 'FAILED' (FAILED: ex., OUT_OF_BALANCE, COOLDOWN_ACTIVE) | Cartões válidos rejeitados por violação de regra de negócio, como saldo pré-pago insuficiente, perímetro GPS ou intervalo de espera OncePerDayRule. |
Em caixas POS integradas que invocam POST /v1/pos/redeem, as transações registam também PosOperation (DISCOUNT | ADD_POINTS | DEDUCT_VALUE | ADD_STAMPS | VOID | CUSTOM) e walletPropagation (PosWalletPropagationStatus: QUEUED | SKIPPED), consultáveis via GET /v1/pos/admin/logs.
Relatórios Dimensionais: Locais, Configurações e Operadores
Os relatórios de validação podem ser filtrados e agrupados segundo cinco dimensões operacionais:
-
1
Configuração de Scanner (
scannerConfigurationId): Compare o rendimento entre perfis distintos (ex.: Check-in VIP comCHECK_IN scan modevs. Caixa Cafetaria Adicionar Carimbo comStampCardAddRule). -
2
Local de Validação e Perímetro GPS: Agrupe resgates por loja, entrada de recinto ou raio de coordenadas GPS para medir a afluência por espaço físico.
-
3
Operador e Terminal (
operatorId,terminalId): Audite o volume de leituras e montantes introduzidos manualmente por operador, nome de dispositivo (deviceName) ou caixa POS. -
4
Canal e Protocolo (
channel,protocol): Acompanhe leituras óticas (QR,PDF417,CODE128,AZTEC) face a toques sem contacto (NFCviaVAS,SMART_TAP,NDEFouJWT). -
5
Efeitos em Saldo Pré-Pago e Fidelização (
effects): Concilie o total destampsAdded, variação líquidapointsDeltae créditos/débitostransactionAmountpor moeda (ISO-4217).
Consultar Registos de Auditoria de Leitura e Livro-Razão via API
Esquema do Evento de Leitura e Payload do Livro-Razão
Ao consultar o histórico de leituras (GET /api/v1/validation/configs/:id/scans ou GET /api/v1/scans/result/:scanId), cada evento fornece contexto completo de diagnóstico e movimentos financeiros:
GET /api/v1/scans/result/scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c HTTP/1.1
Host: api.passinstance.com
x-scanner-key: <scanner_api_key>
Payload de Resposta (200 OK)
{
"scanId": "scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c",
"timestamp": "2026-11-16T08:42:11.304Z",
"decision": "SUCCESS",
"status": "ACCEPTED",
"reasonCode": null,
"channel": "NFC",
"protocol": "VAS",
"resolvedConfigId": "cfg_7d82a100-3c4b-4e12-9a88-112233445566",
"passSnapshot": {
"id": "pas_55a19c88-102b-4f33-8d99-ccddff001122",
"templateId": "b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
"serialNumber": "PI-2026-994812",
"externalId": "CRM-88210",
"status": "ACTIVE",
"tier": "GOLD"
},
"effects": {
"oldBalance": "45.00",
"newBalance": "32.50",
"transactionAmount": 12.50,
"currency": "EUR",
"amountBalanceBehavior": "ADD_VALUE",
"pointsDelta": 125,
"stampsAdded": 0
},
"ruleTrace": [
{ "rule": "PassStatusRule", "passed": true },
{ "rule": "ExpirationRule", "passed": true },
{ "rule": "PrepaidCardRule", "passed": true, "deducted": 12.50 },
{ "rule": "LoyaltyProgramRule", "passed": true, "awardedPoints": 125 }
]
}
Documentação Relacionada
-
Exporte históricos completos de leitura e inventários de chaves em Exportação de Dados e Relatórios.
-
Explore gráficos de telemetria do espaço de trabalho no Painel Analítico.
