Documentação

Português

English
Español

Português

English
Español

Appearance

Clube de Recompensas — Programa ​

Pré-requisitos de acesso

  • Permissão (módulo): viewRewardsProgram (para ler) / manageRewardsProgram (para salvar)
  • Licença/Feature: REWARDS_CLUB
  • Contêiner do menu: GERAL → grupo Clube de Recompensas

O que é / quando usar ​

A tela Programa é o singleton de configuração do Clube de Recompensas (RCS) para o tenant. Aqui você define a identidade do clube, como o nível (tier) do usuário é calculado (métrica + janela), os caps anti-fraude globais, as pools de pagamento (carteiras-casa por asset) e as cotações manuais usadas quando não há price-feed automático.

Use ao montar o clube pela primeira vez e sempre que precisar mudar a regra macro (ex.: passar de "volume de depósitos" para "pontos de missão", pausar payouts em emergência, abastecer/monitorar a pool de pagamento).

Pré-condições ​

  • Permissão: viewRewardsProgram para abrir; manageRewardsProgram para que os controles fiquem editáveis e o Salvar funcione (permissão dupla: enum CPM + módulo dinâmico no DB).
  • Licença/Feature: REWARDS_CLUB habilitada na licença do tenant (Vault). Se desabilitada, o grupo nem aparece no menu.
  • Dependências de outras telas: os níveis são criados em Níveis e as missões em Missões. Quando a métrica de tier é POINTS, é preciso ter missões que concedem pontos.

Passo a passo ​

  1. Acesse o menu Clube de Recompensas → Programa (/rewards-club/program).
  2. Defina Status (Ativo/Pausado) e o nome do programa.
  3. Escolha a Métrica do tier (volume de depósitos, volume negociado ou pontos de missão) clicando no card correspondente.
  4. Escolha a Janela do tier (vitalícia, últimos 90 dias ou ano corrente).
  5. Configure o asset padrão de recompensa e o fiat de referência.
  6. Ajuste os caps anti-fraude (por dia, por usuário/dia).
  7. Cadastre as pools de pagamento (uma carteira-casa por asset) e, se necessário, as cotações manuais.
  8. Clique em Salvar — a mutação exige step-up (ver abaixo).

Campos ​

CampoO que éObrigatório?Efeito no sistema/backend
Status (status)ACTIVE ou PAUSEDSimAtivo: eventos disparam payouts e o tier engine recomputa em ciclo. Pausado: eventos continuam auditados, mas missões não pagam; o tier engine segue rodando. Use Pausado em emergências.
Métrica do tier (tierMetric)Como o nível é calculadoSimDEPOSIT_VOLUME (soma de depósitos confirmados em fiat), TRADE_VOLUME (volume negociado em fiat) ou POINTS (pontos de missão). Valores canônicos do rcs-lib — definem o que o engine soma para posicionar o usuário num tier.
Janela do tier (tierWindow)Período considerado na métricaSimLIFETIME (acumulado vitalício — nunca desce de nível), ROLLING_90D (janela rolante de 90 dias — pode perder o nível), CALENDAR_YEAR (reseta em 1º de janeiro).
Asset padrão de recompensa (defaultRewardAsset)Token/asset usado quando a missão não define umNãoQuando uma missão não tem rewardAssetId, o payout usa este asset. Torna o token de recompensa configurável e modular (ex.: tBRL, MID, USDC) — sem travar em fiat.
Fiat de referência (referenceFiat)Moeda de exibição da métrica financeiraCondicionalUsado para exibir a métrica quando ela é DEPOSIT_VOLUME/TRADE_VOLUME. Quando a métrica é POINTS, a UI exibe em "pts" e ignora este campo. Substitui o fiatRef legado (espelhado para retrocompat).
Cap global por dia (globalMaxPayoutsPerDay)Limite anti-bot de payouts/24h no programa todoNão0 = sem limite.
Cap por usuário/dia (globalMaxPayoutsPerUserPerDay)Limite anti-bot de payouts/24h por usuário (todas as missões)Não0 = sem limite. Camada de proteção independente do cap por missão.
Pools de pagamento (pools[])Carteiras-casa que seguram o saldo de payout por assetSim (para pagar)Cada pool tem assetId, walletAddress, balance (saldo) e minBalanceAlert (limite de alerta). A barra de saldo fica vermelha quando balance ≤ minBalanceAlert. Sem pool com saldo, o asset não consegue pagar.
Cotações manuais (manualQuotes)Override de cotação asset → fiat de referênciaNãoMap ASSET → valor (1 unidade do asset = N de fiat). Usado pelo QuoteService do RCS quando não há price-feed automático para esse par. Linhas em branco são ignoradas no salvar.

O mapa NFTs por tier (tierNftAssets) aparece aqui apenas como leitura (retrocompat com programas legados). A geração da NFT de cada nível mudou para a tela Níveis (botão "Gerar NFT" por linha).

Ações e modais ​

  • Salvar: persiste o programa via PUT /v1/rewards-club/admin/program. Exige step-up (X-Step-Up-Token: re-autenticação senha + MFA, janela de 5 min). Se o token expirar, o gateway responde 428 Step-up required e o interceptor solicita nova verificação.
  • Adicionar/Remover pool e Adicionar/Remover cotação manual: manipulam as listas localmente; só são persistidos no Salvar.

Regras de negócio / cuidados ​

Atenção

  • Pausar o programa não para a captura de eventos (auditoria continua) — apenas suspende os pagamentos. Útil para conter um incidente sem perder o histórico.
  • A escolha entre LIFETIME e janelas rolantes muda profundamente o comportamento: em LIFETIME o usuário nunca desce de nível; em ROLLING_90D/CALENDAR_YEAR ele pode perder o tier.
  • Trocar a métrica para POINTS sem missões pontuadoras configuradas deixa todos no nível base. Garanta missões com missionPoints > 0 antes.
  • Mantenha as pools abastecidas: saldo abaixo do alerta sinaliza risco de payouts falharem por falta de fundos na carteira-casa.
  • Valores financeiros: saldos, alertas e cotações trafegam como string BigNumber — sem arredondamento; trate como BigNumber antes de qualquer aritmética.
  • Idempotência: os payouts subjacentes passam pela FinLib, que é idempotente por externalId. O código de erro E00021 ("already processed") significa sucesso (já liquidado), não falha.

Exemplos ​

Cenário 1 — Clube de captação por volume de depósitos (vitalício)

Objetivo: premiar quem mais deposita, sem nunca rebaixar.

  1. Status = Ativo.
  2. Métrica = "Volume de depósitos".
  3. Janela = "Vitalícia".
  4. Fiat de referência = BRL.
  5. Asset padrão de recompensa = tBRL.
  6. Cadastre uma pool tBRL com a carteira-casa e um minBalanceAlert confortável.
  7. Salve (step-up). Os thresholds de cada nível (em BRL) são definidos em Níveis.
Cenário 2 — Clube de engajamento por pontos (rolante 90 dias)

Objetivo: premiar atividade contínua; quem para, desce.

  1. Métrica = "Pontos de missão".
  2. Janela = "Últimos 90 dias".
  3. Crie missões com missionPoints > 0 (login diário, streak, ordens) em Missões.
  4. Em Níveis, os thresholds passam a ser exibidos em pts (não em fiat).
  5. Salve (step-up).
Cenário 3 — Conter um incidente sem perder histórico

Suspeita de abuso/bot disparando payouts:

  1. Abra Programa e mude Status para Pausado, salve (step-up).
  2. Os eventos continuam sendo capturados e auditados, mas nenhuma missão paga.
  3. Ajuste os caps anti-fraude (globalMaxPayoutsPerUserPerDay > 0) e revise as missões suspeitas.
  4. Volte o status para Ativo quando estiver seguro.

Telas relacionadas ​