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=...ouGET /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
Endpoints de Pesquisa, Auditoria e Exportação de Leituras
| Método | Endpoint | Auth / Guard | Descrição |
|---|---|---|---|
| GET | /api/v1/scans/pass | x-scanner-key | Consulta 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/:barcodeValue | x-scanner-key | Consulta só de leitura do passe por parâmetro de caminho devolvendo IPassLookupResponse. |
| GET | /api/v1/scans/result/:scanId | x-scanner-key | Obtém o resultado completo e ruleTrace de uma leitura específica pelo seu UUID scanId. |
| GET | /api/v1/scans/operations/:idempotencyKey | x-scanner-key | Obtém o comprovativo request payload armazenado para um cabeçalho x-idempotency-key submetido anteriormente. |
| GET | /api/v1/validation/scans | JWT do Espaço de Trabalho / Chave API | Lista registos de leitura paginados do espaço de trabalho para o Painel (/scanner). |
| GET | /api/v1/validation/scans/:scanId | JWT do Espaço de Trabalho / Chave API | Obté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/export | JWT do Espaço de Trabalho / Chave API | Exporta o histórico de leituras restrito a uma ScannerConfiguration específica em CSV. |
| GET | /api/v1/validation/scans/export | JWT do Espaço de Trabalho / Chave API | Exporta registos de leitura e resgate de todo o espaço de trabalho em CSV. |
| GET | /api/v1/validation/scan-results/export/csv | JWT do Espaço de Trabalho / Chave API | Transmite 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) | Estado | reasonCode Típico | Ação Recomendada para Equipa / POS |
|---|---|---|---|
SUCCESS | ACCEPTED | RULE_ACCEPTED | Conceder entrada (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), aplicar desconto ou confirmar dedução de saldo. |
ALREADY_VOIDED | REJECTED | PASS_VOIDED_AFTER_SCAN | Recusar resgate; o passe já foi consumido numa leitura prévia de utilização única. |
ALREADY_USED | REJECTED | ONCE_PER_DAY_LIMIT_REACHED | Informar o titular de que a sua quota diária ou de check-in (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) foi utilizada. |
EXPIRED | REJECTED | PASS_EXPIRED | Encaminhar o cliente para renovar a adesão ou reclamar uma oferta de campanha ativa. |
FAILED | REJECTED | OUT_OF_BALANCE / GEOFENCE_MISMATCH | Verificar detalhes de ruleTrace (ex.: saldo pré-pago insuficiente ou ponto de verificação incorreto). |
INVALID | REJECTED | PASS_NOT_FOUND / INVALID_NONCE | O código de barras não pertence a este espaço de trabalho/modelo ou o nonce anti-repetição expirou. |
PENDING | PENDING | OPERATOR_INPUT_REQUIRED | Solicitar 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)
{
"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):
/api/v1/scans/pass?barcode=PI-GFT-550192
{
"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.
