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.
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 aconfig.pointsPerScanou1. -
Para integrações POS e e-commerce, os pontos são calculados dinamicamente com base no montante da compra:
earnedPoints = floor(purchaseTotal * pointsMultiplier)
newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
-
Se
autoResetAtMaximum: trueouconfig.onCap === "reset", o saldo de pontos repõe pararesetTargetValue(ou para o saldo inicial) ao atingirmaximumValue.
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
/api/v1/mechanics/redeem
{
"passId": "8f94d930-b302-4fc8-9f12-000000000001",
"mechanicId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
"idempotencyKey": "redeem_tx_88194"
}
Resposta HTTP (200 OK)
{
"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/:customerIdou webhooks do plugin Shopware) e credite automaticamente os passes em carteira dos clientes correspondentes porexternalId. -
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 scannerPOST /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.
