Skip to content
Guia da Central de Ajuda
3 min de leituraVerificado 2026-11-16

Relatórios de leitura e resgate

Analise leituras por Local de Validação, totais acumulados de mecânicas e frequência de regresso.

Neste guia

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

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
TELEMETRIA DE VALIDAÇÃO E RESGATE DE LEITURAS
ETAPA 01 CANAIS DE INGESTÃO DE SCANNER E POS
Scanner Móvel / Web
POST/api/v1/scans
Terminal POS de Loja
POST/v1/pos/redeem
Leitor NFC Hardware
`/api/v1/reader/redeem
ETAPA 02 MOTOR DE VALIDAÇÃO DE NEGÓCIO COM 14 REGRAS
1
Regras Base: PassStatusRuleExpirationRuleTimeWindowRule
GeofencingRule
2
Mecânicas: OncePerDayRuleStampCardAddRulePrepaidCardRule
LoyaltyProgramRuleTierEvaluationRule
3
Segurança: RateLimitRuleAntiReplayRule (scan nonce)
ETAPA 03 ARMAZÉM ANALÍTICO DE LEITURAS E LIVRO-RAZÃO
Detalhe scan status | | S
(SUCCESS, EXPIRED, CHECK_IN_SUCCESS...)
mentação dimension.| | A
(scannerConfigId, operatorId, Local)
egados de saldo
e variação pontos no livro-razão

Importante: Cada resposta de leitura grava um array completo ruleTrace juntamente com operatorId, terminalId, scannerConfigurationId, externalId e coordenadas GPS location, 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étricadecision / scan status subjacenteSignificado Operacional
totalScansTodos os eventos de leituraTotal de apresentações de código de barras ou NFC recebidas pelo motor de validação no período consultado.
successfulScansdecision: '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).
duplicateScansdecision: '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.
expiredScansdecision: 'EXPIRED' (EXPIRED)Apresentação de cartões cuja expirationDate já terminou.
rejectedScansdecision: 'INVALID' (INVALID)Dados de código de barras desconhecidos, séries de outro inquilino ou assinaturas criptográficas NFC inválidas.
failedScansdecision: '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. 1
    Configuração de Scanner (scannerConfigurationId): Compare o rendimento entre perfis distintos (ex.: Check-in VIP com CHECK_IN scan mode vs. Caixa Cafetaria Adicionar Carimbo com StampCardAddRule).
  2. 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. 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. 4
    Canal e Protocolo (channel, protocol): Acompanhe leituras óticas (QR, PDF417, CODE128, AZTEC) face a toques sem contacto (NFC via VAS, SMART_TAP, NDEF ou JWT).
  5. 5
    Efeitos em Saldo Pré-Pago e Fidelização (effects): Concilie o total de stampsAdded, variação líquida pointsDelta e créditos/débitos transactionAmount por 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:

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

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

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.