Skip to content
Guia da Central de Ajuda
3 min de leituraVerificado 2026-11-16

Programas de recompensas e pontos

Estruture programas por níveis Pontos & Patamares com regras de acumulação, subidas de nível e alertas.

Neste guia

Visão geral

Ao contrário dos cartões de carimbos com limiar fixo, os Programas de recompensas e fidelização modelam acumulação contínua de pontos e progressão multipatamar (ex.: Bronze -> Prata -> Ouro -> Platina). A Passinstance fornece um motor empresarial de fidelização com regras dinâmicas de acumulação por valor gasto, avaliação automática de patamares, APIs de resgate de recompensas e atualizações push em tempo real na carteira.

Arquitetura no backend e motor de fidelização

Os programas de fidelização combinam o acompanhamento contínuo do saldo com definições estruturadas de patamares no esquema Passinstance database:

  • Tipo de Passe (pass type): storeCard (exibe o saldo ativo de pontos em zonas principais de destaque).
  • Modelo Demo de Catálogo: retail-loyalty.
  • Tipo de Mecânica (mechanic type): LOYALTY_PROGRAM.
  • Principais Modelos de Fidelização:

- Tier: Configura requisitos de limiar (ex.: 500 pontos para Prata, 1.500 pontos para Ouro), benefícios do nível, cores visuais personalizadas e ícones dedicados de distintivo do nível. - BalanceChange: Livro-razão imutável de transações que regista cada acumulação de pontos, dedução por resgate e ajuste administrativo.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
ACUMULAÇÃO DE PONTOS E SUBIDA DE PATAMAR
ATORES DE SISTEMA PARTICIPANTES
P1 Compra POS / E-Commerce
P2 API Principal Passinstance
P3 Tier Progression Engine
P4 Carteira do Cliente
ETAPA CTX CONTEXTO Compra: €120120 Pts
ETAPA 1 PEDIDO / AÇÃO POST/api/v1/passes/:id/use
ETAPA 2 PEDIDO / AÇÃO Atualizar Saldo
›
{ action: "INCREMENT", value }
›
(cur + step clamped)
ETAPA 3 PEDIDO / AÇÃO Avaliar Patamares
›
(Limiar Atingido:
›
PrataOuro)
ETAPA 4 RESPOSTA Patamar Promovido
ETAPA 5 PEDIDO / AÇÃO Push APNs Silencioso
ETAPA 6 RESPOSTA 200 OK (Novo Patamar)
›
e Google REST PATCH | (Cartão muda para Ouro
›
Banner ecrã bloq.:
›
"Promovido a Ouro!")

Motor de acumulação de pontos e progressão de patamares

O Pass Mechanics Engine e o Tier Progression Engine executam as regras de fidelização:

1. Cálculo de acumulação

Quando ocorre uma compra ou visita:

  • O incremento predefinido de pontos utiliza defaultChangeValue (canónico), recorrendo em alternativa a config.pointsPerScan ou 1.
  • Para integrações POS e e-commerce, os pontos são calculados dinamicamente com base no montante da compra:
TEXT
earnedPoints = floor(purchaseTotal * pointsMultiplier)
  newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
  • Se autoResetAtMaximum: true ou config.onCap === "reset", o saldo de pontos repõe para resetTargetValue (ou para o saldo inicial) ao atingir maximumValue.

2. Promoções automáticas de patamar (Tier Progression Engine)

Após cada alteração de saldo, o Tier Progression Engine avalia os pontos acumulados do membro face aos limiares de patamares ativos:

  • Se um patamar for ultrapassado, o serviço promove o membro para o nível superior.
  • Atualiza automaticamente o estilo visual do cartão (alterando cores de fundo, rótulos de cabeçalho e ícones de distintivo do nível).
  • Dispara um push silencioso APNs e uma atualização REST da Google Wallet, alertando o cliente com uma notificação nativa no ecrã bloqueado: "Parabéns! Atingiu o Patamar Ouro."

API de resgate de recompensas

Quando um cliente resgata pontos por descontos, artigos gratuitos ou mercadoria em loja ou online:

Pedido HTTP

POST /api/v1/mechanics/redeem
Cabeçalhos
X-API-Key <API_KEY>
Content-Type application/json
JSON
{
  "passId": "8f94d930-b302-4fc8-9f12-000000000001",
  "mechanicId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
  "idempotencyKey": "redeem_tx_88194"
}

Resposta HTTP (200 OK)

JSON
{
  "success": true,
  "newBalance": 240,
  "newBalanceDecimal": "240",
  "message": "Reward redeemed successfully"
}

E-commerce e sincronização multicanal

Ligue caixas físicas em loja e lojas online para manter um livro-razão unificado do cliente (transaction type: EARN, REDEEM, ADJUST, REFUND, TRANSFER, BONUS, PENALTY, SCAN, API, ADJUSTMENT):

  • Conectores Shopware 6 / Shopify: Receba webhooks de encomendas online (/api/v1/automations/webhooks/shopify/:customerId, /api/v1/automations/webhooks/woocommerce/:customerId ou webhooks do plugin Shopware) e credite automaticamente os passes em carteira dos clientes correspondentes por externalId.
  • API canónica de utilização de passe (POST /api/v1/passes/:id/use): Endpoint programático preferencial de alteração de saldo/pontos para ERPs, apps e serviços backend (com homólogo por chave de scanner POST /api/v1/scans/pass/:passId/use). A ingestão legada de eventos de mecânica (POST /api/v1/mechanics/:mechanicId/events) mantém retrocompatibilidade, embora desaconselhada em novas integrações.

Importante: Configure changeMessage: "Points balance updated to %@" no campo principal de pontos no editor de modelos. Sempre que são acumulados ou deduzidos pontos, o ecrã bloqueado do cliente mostra de imediato o saldo atualizado.

Saiba mais sobre a nossa Solução de Fidelização, explore Cartões de Fidelização ou consulte o Guia de Regras de Progressão de Fidelização.

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.