Skip to content
Guia da Central de Ajuda · Resgates e transaçõesFase de integração 2
4 min de leituraVerificado 2026-11-16

Pontos de fidelidade e carimbos

Atribua carimbos na leitura, reinicie cartões completos, some pontos por visita e avalie subidas de patamar.

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

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-Key ou campo idempotencyKey). 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

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
FLUXO DA ARQUITETURA DO SISTEMA: ACUMULAÇÃO DE FIDELIDADE, PATAMAR E RESGATE DE RECOMPENSA
ATORES DE SISTEMA PARTICIPANTES
P1 Terminal Scanner / POS
P2 Loyalty & Stamp Engine / Mecânicas
P3 Tier Progression Engine e Push Carteira
ETAPA 1 PEDIDO / AÇÃO POST/api/v1/scans
ETAPA 2 PEDIDO / AÇÃO Executa ScanAction / Mecânica:
›
{ action: "INCREMENT" }
›
INCREMENT / DECREMENT
›
CREDIT / DEBIT / SET
›
STAMP_CARD / LOYALTY_PROGRAM
ETAPA 3 PEDIDO / AÇÃO Verifica Limiares Patamar
ETAPA 4 PEDIDO / AÇÃO Hidrata Recursos e Cores
ETAPA 5 RESPOSTA Persiste Saldo e Razão
ETAPA 6 RESPOSTA 200 OK (resultingValue)
ETAPA 7 PEDIDO / AÇÃO Emite eventos POINTS_UPDATED /
›
8. Push APNs e Google Wallet
›
TIER_CHANGED
›
(Faixa e Emblema Atualiz.)

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):

EndpointAuth / GuardFinalidade Principal
POST /api/v1/scans/pass/:passId/usex-scanner-keyAlteração de carimbos, pontos ou saldo iniciada pelo scanner através de request payload.
POST /api/v1/passes/:id/useJWT do Espaço de Trabalho / Chave APIExecução de carimbos ou pontos num passe iniciada por CRM de backend/webhook.
POST /api/v1/mechanics/redeemChave 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/stateChave de Scanner ou JWTDevolve o saldo atual de carimbos/pontos mais os sinalizadores de capacidade allowedActions.
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledgerChave de Scanner ou JWTLista transações históricas da mecânica (?limit=50, máx. 500).
GET /api/v1/balance-changesJWT do Espaço de Trabalho / Chave APIConsulta 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:

POST /api/v1/scans/pass/pass_loy_884120/use
Cabeçalhos
x-scanner-key sk_live_cafe_counter_01
Idempotency-Key 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Content-Type application/json
JSON
{
  "action": "INCREMENT",
  "mechanicId": "11111111-2222-4333-8444-555555555555",
  "amount": "2",
  "deviceId": "ios-idfv-cafe-03",
  "operatorId": "barista_03",
  "location": "Main Counter"
}
Campo (request payload)TipoValidação / Notas
actionenum (opcional, predefinição INCREMENT)Um de 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'.
mechanicIdUUID (opcional)Verifica a mecânica de destino associada a este passe.
amountstring decimal (opcional)Tem de corresponder a /^\d+(\.\d{1,6})?$/ (ex. "2" ou "12.90").
deviceId / operatorId / locationstrings (opcional)Registados no livro-razão de auditoria para reconciliação de turnos.
idempotencyKeystring (opcional)Tem de corresponder ao cabeçalho Idempotency-Key caso ambos sejam fornecidos.

Resposta (200 OK — IPassUseResponse):

JSON
{
  "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

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):

JSON
{
  "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. 1
    Avaliação de Limiar: Verifica se o saldo atualizado entra num patamar superior (ex.: Bronze: 0–249, Silver: 250–499, Gold: 500+).
  2. 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. 3
    Alerta de Celebração no Ecrã Bloqueado: Despoleta uma notificação changeMessage da Apple Wallet (ex.: "Congratulations! You reached Gold Tier") e emite o gatilho de fluxo de trabalho TIER_CHANGED para 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.

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.