Skip to content
Guia da Central de AjudaFase de integração 2
4 min de leituraVerificado 2026-11-16

Cartões de fidelidade e carimbos

Crie cartões digitais com grelha visual de carimbos, incremento por visita e emissão automática de prémios.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface
Elementos-chave da interface

Seletor «Adicionar uma mecânica de cartão» (Zoom)

Escolha entre 6 mecânicas integradas: Cartão de carimbos, Resgate de carimbos, Valor armazenado, Pontos e níveis, Validação uma vez por dia ou Prolongar validade.

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-card e coffee-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.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
CICLO DO CARTÃO DE CARIMBOS E GESTÃO DE LIMITE
ETAPA 01 PIPELINE DE PROGRESSÃO
1
Leitura Inicial (0 Carimbos)
2
+1 Carimbo por Visita
3
Cartão Atinge maximumValue (ex.: 8)
ETAPA 02A onCap: "noop"
Cartão fixa em 8/8
Ação Aplicada: NOOP
Solicita resgate à equipa
ETAPA 02B onCap: "reset"
Recompensa atribuída
Contador volta a 0
Novo ciclo recomeça logo
ETAPA 02C Validação Predefinida
Devolve HTTP 400
"Cartão de carimbos cheio; reclame primeiro"

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. 1
    Incremento de carimbos: Adiciona defaultChangeValue (predefinição 1) ao saldo atual do passe:
TEXT
newStamps = clamp(currentStamps + defaultChangeValue, 0, maximumValue)
  1. 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).

  1. 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.

  1. 4
    Correlação CRM (externalId): Associe o ID do membro de fidelidade a Pass.externalId para que atualizações de carimbos do POS, loja online e app móvel possam fazer upsert sem falhas via POST /api/v1/passes/upsert-by-external-id.
Cartões de seleção de mecânica do modelo
Cartões de seleção de mecânica do modelo

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.

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.