Visão geral
Os Cartões de fidelização e carimbos digitalizam os tradicionais cartões de papel perfurados ("Compre 8 cafés e o 9.º é grátis") em passes nativos interativos para carteiras digitais móveis. Os clientes nunca perdem o cartão, a equipa regista carimbos na caixa em dois segundos com leitura ótica QR e os comerciantes impulsionam visitas repetidas através de notificações automáticas no ecrã bloqueado.
Arquitetura no backend e enums de mecânicas
Os cartões digitais de carimbos combinam imagens de faixa visuais com execução determinística de regras em Pass Mechanics Engine:
-
Tipo de Passe (pass type):
storeCard. -
Modelos Demo de Catálogo:
restaurant-stamp-cardecoffee-loyalty. -
Tipos de Mecânica (mechanic type):
- STAMP_CARD_ADD: Incrementa a contagem ativa de carimbos em defaultChangeValue (habitualmente 1). - STAMP_CARD_DEDUCT: Permite aos operadores de caixa corrigir carimbos acidentais ou deduzir carimbos em resgates parciais.
-
Configuração visual da grelha de carimbos:
- Matriz StampImage: Mapeia estados individuais de ativos visuais para posições de carimbo 0..N (apresentados nas imagens de faixa Apple e imagens modulares da Google Wallet). - maximumValue: Total de carimbos necessários para completar o cartão (ex.: 8 ou 10). - rewardImageResourceId: Ícone personalizado de troféu ou recompensa revelado quando o cartão atinge a capacidade total.
Lógica de execução do motor de carimbos e comportamentos de limite
Quando um operador ao balcão lê o passe do cliente, o Pass Mechanics Engine avalia os limiares ativos:
-
1
Incremento de carimbos: Adiciona
defaultChangeValue(predefinição1) ao saldo atual do passe:
newStamps = clamp(currentStamps + defaultChangeValue, 0, maximumValue)
-
2
Gestão de limite (
onCap) e semântica de ação (scan action / transaction type):
- onCap: "noop": Quando o cartão atinge o máximo de carimbos, o motor devolve { ok: true, reason: "Card is full", appliedAction: "NOOP" }. O passe permanece completo para que a equipa inspecione o cartão concluído e entregue a recompensa. - onCap: "reset": Despoleta automaticamente o evento de recompensa e repõe os carimbos a 0: { ok: true, reason: "Card reset" }. - Comportamento predefinido: Devolve { ok: false, reason: "Stamp card is full" }, indicando à equipa que deve iniciar um fluxo separado de resgate (POST /api/v1/mechanics/redeem ou POST /api/v1/passes/:id/use com scan action: INCREMENT, DECREMENT, VALIDATE, registado com transaction type: EARN, REDEEM, ADJUST, SCAN).
-
3
Comportamentos de reclamação da recompensa (
rewardClaimBehavior):
- RESET_TO_ZERO: Repõe todos os carimbos para 0 após resgate pela equipa. - START_NEW_CYCLE: Transita quaisquer carimbos excedentários de compras com múltiplos artigos para o ciclo de recompensas seguinte. - KEEP_COMPLETED: Mantém o estado visual completo até o vale de recompensa ser reclamado.
-
4
Correlação CRM (
externalId): Associe o ID do membro de fidelidade aPass.externalIdpara que atualizações de carimbos do POS, loja online e app móvel possam fazer upsert sem falhas viaPOST /api/v1/passes/upsert-by-external-id.

Proteção de leitura diária (VALID_ONCE_PER_DAY)
Para impedir duplos registos acidentais ou abusos na caixa, associe a regra secundária VALID_ONCE_PER_DAY:
-
O motor resolve o fuso horário da localização do comerciante através de
resolveCustomerTimeZone. -
Se um colaborador ler o mesmo cartão de cliente duas vezes no mesmo dia civil, a segunda leitura devolve um aviso informativo (
ALREADY_SCANNED_TODAY) sem adicionar um segundo carimbo não autorizado.
Atualizações no ecrã bloqueado em tempo real
Sempre que um carimbo é adicionado ou resgatado:
-
A Passinstance envia uma notificação silenciosa APNs para o iPhone do cliente.
-
A Apple Wallet atualiza a faixa visual de carimbos e exibe um alerta no ecrã bloqueado: "Ganhou um carimbo! Tem agora 5 de 8 carimbos."
-
A Google Wallet atualiza o cartão em direto e apresenta uma notificação no Android.
Importante: As imagens dinâmicas da faixa de carimbos são geradas automaticamente em resoluções retina (@1x, @2x, @3x) pelo motor gráfico da Passinstance, garantindo carimbos nítidos em ecrãs de smartphone de elevada densidade.
Leia a nossa visão geral completa de Cartões de Carimbos Digitais, explore Restaurantes e Cafés ou consulte o Guia de Regras de Coleção de Carimbos.
