Skip to content
Guia da Central de Ajuda · Leitura de passes
4 min de leituraVerificado 2026-11-16

Histórico e resultados de leitura

Audite resultados (VALID, ALREADY_REDEEMED, EXPIRED, VOIDED), registos horários, lojas e respostas.

Neste guia

Visão geral

Cada pedido de validação processado pela Passinstance gera um registo de auditoria imutável contendo o parâmetro decision avaliado, reasonCode, o ruleTrace passo a passo, metadados do operador e os saldos anteriores e posteriores do passe. Pode rever o histórico de leituras visualmente no Painel em Scanner (/scanner), inspecionar comprovativos individuais de leitura, consultar resultados de operações idempotentes, efetuar pesquisas de passes sem mutação ou descarregar exportações CSV completas para reconciliação contabilística.

Importante: As rotas de consulta só de leitura (GET /api/v1/scans/pass?barcode=... ou GET /api/v1/scans/pass/:barcodeValue) permitem aos terminais POS e balcões de apoio ao cliente inspecionar o estado do passe, externalId, patamar e saldo sem registar um evento de leitura, incrementar contadores ou anular vales de utilização única.

Arquitetura e Fluxo de Consulta de Auditoria

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
FLUXO DA ARQUITETURA DO SISTEMA: COMPROVATIVO DE LEITURA E PIPELINE DE EXPORTAÇÃO
ATORES DE SISTEMA PARTICIPANTES
P1 Cliente POS / Scanner
P2 Scan Validation API (/api/v1/scans)
P3 Validation Config API (/api/v1/validation)
ETAPA 1 PEDIDO / AÇÃO GET/scans/pass?barcode=...
ETAPA 2 RESPOSTA 200 OK (IPassLookupResponse)
ETAPA 3 PEDIDO / AÇÃO GET/scans/operations/:idem
ETAPA 4 RESPOSTA 200 OK (ScanResponse cache)
ETAPA 5 PEDIDO / AÇÃO GET/scans/result/:scanId
ETAPA 6 RESPOSTA 200 OK (ruleTrace completo)
ETAPA 7 PEDIDO / AÇÃO GET/validation/scan-results/export/csv
ETAPA 8 RESPOSTA 200 OK (stream text/csv: scan_id, decision, operator, effects)

Endpoints de Pesquisa, Auditoria e Exportação de Leituras

MétodoEndpointAuth / GuardDescrição
GET/api/v1/scans/passx-scanner-keyConsulta só de leitura do passe através do parâmetro ?barcode=... (recomendado para payloads em formato URL). Não cria um registo de leitura.
GET/api/v1/scans/pass/:barcodeValuex-scanner-keyConsulta só de leitura do passe por parâmetro de caminho devolvendo IPassLookupResponse.
GET/api/v1/scans/result/:scanIdx-scanner-keyObtém o resultado completo e ruleTrace de uma leitura específica pelo seu UUID scanId.
GET/api/v1/scans/operations/:idempotencyKeyx-scanner-keyObtém o comprovativo request payload armazenado para um cabeçalho x-idempotency-key submetido anteriormente.
GET/api/v1/validation/scansJWT do Espaço de Trabalho / Chave APILista registos de leitura paginados do espaço de trabalho para o Painel (/scanner).
GET/api/v1/validation/scans/:scanIdJWT do Espaço de Trabalho / Chave APIObtém um registo de auditoria de leitura e rasto único do espaço de trabalho para inspeção no Painel.
GET/api/v1/validation/configs/:id/scans/exportJWT do Espaço de Trabalho / Chave APIExporta o histórico de leituras restrito a uma ScannerConfiguration específica em CSV.
GET/api/v1/validation/scans/exportJWT do Espaço de Trabalho / Chave APIExporta registos de leitura e resgate de todo o espaço de trabalho em CSV.
GET/api/v1/validation/scan-results/export/csvJWT do Espaço de Trabalho / Chave APITransmite por streaming o rasto de auditoria completo de leituras incluindo resultados de avaliação de regras (text/csv).

Resultados de Decisão (request payload) vs. scan status Persistido

A API devolve um enum decision de alto nível (SUCCESS | FAILED | ALREADY_USED | ALREADY_VOIDED | EXPIRED | INVALID | PENDING) em request payload, enquanto persiste o scan status granular (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT) no registo de leitura subjacente:

Decisão (request payload)EstadoreasonCode TípicoAção Recomendada para Equipa / POS
SUCCESSACCEPTEDRULE_ACCEPTEDConceder entrada (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), aplicar desconto ou confirmar dedução de saldo.
ALREADY_VOIDEDREJECTEDPASS_VOIDED_AFTER_SCANRecusar resgate; o passe já foi consumido numa leitura prévia de utilização única.
ALREADY_USEDREJECTEDONCE_PER_DAY_LIMIT_REACHEDInformar o titular de que a sua quota diária ou de check-in (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) foi utilizada.
EXPIREDREJECTEDPASS_EXPIREDEncaminhar o cliente para renovar a adesão ou reclamar uma oferta de campanha ativa.
FAILEDREJECTEDOUT_OF_BALANCE / GEOFENCE_MISMATCHVerificar detalhes de ruleTrace (ex.: saldo pré-pago insuficiente ou ponto de verificação incorreto).
INVALIDREJECTEDPASS_NOT_FOUND / INVALID_NONCEO código de barras não pertence a este espaço de trabalho/modelo ou o nonce anti-repetição expirou.
PENDINGPENDINGOPERATOR_INPUT_REQUIREDSolicitar ao operador de caixa o preenchimento dos campos obrigatórios em scanForm (como montante da transação).

Inspecionar uma Leitura Concluída (GET /api/v1/scans/result/:scanId)

JSON
{
  "scanId": "scan_01hxyz7712ab",
  "idempotencyKey": "idem_reg04_20261116_0091",
  "timestamp": "2026-11-16T09:42:11.000Z",
  "decision": "ALREADY_USED",
  "status": "REJECTED",
  "reasonCode": "ONCE_PER_DAY_LIMIT_REACHED",
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true, "durationMs": 1 },
    { "rule": "ExpirationRule", "passed": true, "durationMs": 1 },
    {
      "rule": "OncePerDayRule",
      "passed": false,
      "reasonCode": "ONCE_PER_DAY_LIMIT_REACHED",
      "lastScanAt": "2026-11-16T06:15:04.000Z",
      "durationMs": 3
    }
  ],
  "passSnapshot": {
    "id": "pass_gym_8821",
    "templateId": "tmpl_gym_member",
    "serialNumber": "PI-GYM-8821",
    "externalId": "crm_member_8821",
    "status": "ACTIVE"
  }
}

Consulta de Passe Sem Mutação (GET /api/v1/scans/pass)

Antes de submeter uma leitura com mutação ou um débito POS, um terminal pode consultar o estado atual de um passe através de GET /api/v1/scans/pass?barcode=PI-GFT-550192 (prefira ?barcode= em vez do parâmetro de caminho sempre que os códigos de barras contenham barras / ou URLs):

GET /api/v1/scans/pass?barcode=PI-GFT-550192
Cabeçalho
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "passId": "pass_gft_550192",
  "templateId": "tmpl_giftcard_eur",
  "templateName": "Retail Gift Card",
  "serialNumber": "PI-GFT-550192",
  "externalId": "shopify_cust_550192",
  "status": "ACTIVE",
  "storedValue": "75.00",
  "expirationDate": "2027-12-31T23:59:59.000Z",
  "isExpired": false,
  "isVoided": false,
  "barcodeValue": "PI-GFT-550192",
  "attributes": {
    "holderName": "Elena Rostova"
  },
  "checkedAt": "2026-11-16T10:15:00.000Z"
}

Exportar Registos de Leituras para CSV

Para reconciliação de turnos, auditorias financeiras ou ingestão em BI, exporte os históricos de leituras diretamente como streams CSV UTF-8 (Content-Type: text/csv; charset=utf-8):

  • Exportação de Configuração Única: GET /api/v1/validation/configs/:id/scans/export?from=2026-11-01&to=2026-11-16
  • Exportação de Todas as Configurações: GET /api/v1/validation/scans/export?templateId=tmpl_loyalty_01
  • Exportação Completa de Resultados de Auditoria: GET /api/v1/validation/scan-results/export/csv

Consulte Relatórios de Leitura e Resgate e Exportação de Dados e Relatórios para opções de agregação analítica.

Documentação de produto e API 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.