Visão geral
A Passinstance processa carimbos em cartões de fidelização, acumulação de pontos, promoções automáticas de patamar e resgates de recompensas através de Loyalty & Stamp Engine, Pass Mechanics API e Tier Progression Engine. A equipa e as integrações de backend podem despoletar atualizações de fidelização mediante uma leitura padrão ao balcão (POST /api/v1/scans), execução direta do passe pelo scanner (POST /api/v1/scans/pass/:passId/use), utilização de passe autenticada pelo espaço de trabalho (POST /api/v1/passes/:id/use), resgate em terminal POS (POST /v1/pos/redeem) ou resgate explícito de recompensa (POST /api/v1/mechanics/redeem).
Importante: Todas as alterações de saldo de fidelização e resgates de recompensas são executados em transações atómicas com imposição estrita de idempotência (cabeçalho
Idempotency-Keyou campoidempotencyKey). Após qualquer alteração de carimbos, pontos ou patamar, a Passinstance regenera automaticamente as imagens dinâmicas da faixa (strip) e envia atualizações push silenciosas para a Apple Wallet e Google Wallet.
Arquitetura e Fluxo de Execução de Mecânicas
Ações de Mecânica Permitidas e Endpoints de Estado
request payload aceita uma de sete ações explícitas (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET), correspondendo à taxonomia do livro-razão scan action (INCREMENT | DECREMENT | VALIDATE | DEBIT | CREDIT | NOOP):
| Endpoint | Auth / Guard | Finalidade Principal |
|---|---|---|
POST /api/v1/scans/pass/:passId/use | x-scanner-key | Alteração de carimbos, pontos ou saldo iniciada pelo scanner através de request payload. |
POST /api/v1/passes/:id/use | JWT do Espaço de Trabalho / Chave API | Execução de carimbos ou pontos num passe iniciada por CRM de backend/webhook. |
POST /api/v1/mechanics/redeem | Chave de Scanner ou JWT (request payload) | Executa um resgate completo de cartão de carimbos ou recompensa (action: 'DECREMENT'). |
GET /api/v1/mechanics/:mechanicId/passes/:passId/state | Chave de Scanner ou JWT | Devolve o saldo atual de carimbos/pontos mais os sinalizadores de capacidade allowedActions. |
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger | Chave de Scanner ou JWT | Lista transações históricas da mecânica (?limit=50, máx. 500). |
GET /api/v1/balance-changes | JWT do Espaço de Trabalho / Chave API | Consulta o histórico de alterações de saldos de fidelização e pré-pagos em todo o inquilino. |
Endpoints para Acumulação de Fidelização e Resgate de Recompensas
1. Execução Direta de Mecânica (POST /api/v1/scans/pass/:passId/use)
Quando um scanner ou terminal POS tiver consultado o passe (GET /api/v1/scans/pass?barcode=...), pode executar uma adição de carimbos, atribuição de pontos ou decréscimo diretamente contra o UUID :passId utilizando request payload:
/api/v1/scans/pass/pass_loy_884120/use
{
"action": "INCREMENT",
"mechanicId": "11111111-2222-4333-8444-555555555555",
"amount": "2",
"deviceId": "ios-idfv-cafe-03",
"operatorId": "barista_03",
"location": "Main Counter"
}
Campo (request payload) | Tipo | Validação / Notas |
|---|---|---|
action | enum (opcional, predefinição INCREMENT) | Um de 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'. |
mechanicId | UUID (opcional) | Verifica a mecânica de destino associada a este passe. |
amount | string decimal (opcional) | Tem de corresponder a /^\d+(\.\d{1,6})?$/ (ex. "2" ou "12.90"). |
deviceId / operatorId / location | strings (opcional) | Registados no livro-razão de auditoria para reconciliação de turnos. |
idempotencyKey | string (opcional) | Tem de corresponder ao cabeçalho Idempotency-Key caso ambos sejam fornecidos. |
Resposta (200 OK — IPassUseResponse):
{
"success": true,
"data": {
"scanId": "scan_01hxyz8820ab",
"passId": "pass_loy_884120",
"action": "INCREMENT",
"success": true,
"resultingValue": "8"
},
"description": "Pass INCREMENT successfully",
"errors": [],
"statusCode": 200
}
2. Resgatar uma Recompensa Desbloqueada (POST /api/v1/mechanics/redeem)
Quando um cliente reclama uma recompensa de cartão de carimbos ganha ou gasta unidades acumuladas, invoque POST /api/v1/mechanics/redeem com request payload:
POST /api/v1/mechanics/redeem Cabeçalhos: x-scanner-key: sk_live_cafe_counter_01 (ou Authorization: Bearer <jwt>) Idempotency-Key: 4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872 Content-Type: application/json
{
"passId": "a1b2c3d4-e5f6-4a7b-8c9d-0123456789ab",
"mechanicId": "11111111-2222-4333-8444-555555555555",
"ruleId": "default",
"idempotencyKey": "4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872"
}
(Nota: Tanto passId como mechanicId — e o idempotencyKey opcional dentro do corpo JSON — têm de ser UUIDs válidos; se fornecido, ruleId tem de ser igual a "default".)
Resposta (200 OK — IRedeemResponse):
{
"success": true,
"newBalance": 0,
"newBalanceDecimal": "0",
"reward": "default",
"message": "Reward redeemed successfully"
}
Subidas Automáticas de Patamar (Tier Progression Engine)
Sempre que uma leitura, POST /api/v1/scans/pass/:passId/use ou POST /v1/pos/redeem (operation: "ADD_POINTS" ou "ADD_STAMPS") altera o saldo de pontos ou visitas de um passe, Tier Progression Engine avalia os limiares de patamar configurados no modelo:
-
1
Avaliação de Limiar: Verifica se o saldo atualizado entra num patamar superior (ex.:
Bronze: 0–249,Silver: 250–499,Gold: 500+). -
2
Hidratação Visual e de Recursos: Substitui as cores de fundo específicas do patamar, as imagens de faixa/banner e os campos de etiqueta do patamar no registo do passe.
-
3
Alerta de Celebração no Ecrã Bloqueado: Despoleta uma notificação
changeMessageda Apple Wallet (ex.: "Congratulations! You reached Gold Tier") e emite o gatilho de fluxo de trabalhoTIER_CHANGEDpara que possa automatizar benefícios de boas-vindas bónus.
Saiba mais sobre como configurar programas de fidelização em Cartões de Fidelização e Carimbos e como automatizar recompensas por patamar em Configuração de Fluxos de Trabalho.
