Documentação

Português

English
Español

Português

English
Español

Appearance

Clube de Recompensas — Missões ​

Pré-requisitos de acesso

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

O que é / quando usar ​

Gerencia as missões do clube: regras orientadas a evento que, quando satisfeitas, concedem recompensa (asset + valor) e/ou pontos. A listagem é em cards com filtros por status, frequência e evento; a criação/edição usa um wizard de 4 passos (Trigger → Identidade → Recompensa → Vigência).

Use para desenhar a gamificação: "primeira ordem paga X", "login diário dá Y pontos", "investir em crowdfunding dá Z", etc. O catálogo cobre 28 eventos suportados, agrupados por categoria (Financeiro, Cadastro & KYC, Indicação, Crowdfunding, Marketplace & NFT, Staking, Volume & Streak, Mudança de Nível).

Pré-condições ​

  • Permissão: viewRewardsProgram para ler; manageRewardsMissions para editar (permissão dupla: enum CPM + módulo dinâmico no DB).
  • Licença/Feature: REWARDS_CLUB.
  • Dependências de outras telas: o asset de recompensa deve existir; se a missão não definir um, o payout usa o asset padrão do Programa. Para missões com missionPoints valerem para o tier, o Programa precisa usar a métrica POINTS.

Passo a passo ​

  1. Acesse o menu Clube de Recompensas → Missões (/rewards-club/missions).
  2. Filtre por status (todas/ativas/inativas), frequência, evento ou texto livre.
  3. Clique em Novo para abrir o wizard.
  4. Passo 1 – Trigger: escolha o evento no catálogo (tabs por grupo + cards explicativos). Aplique exemplos de condition_json ou edite as condições campo a campo.
  5. Passo 2 – Identidade: nome (gera o code/slug automaticamente), descrição, ícone.
  6. Passo 3 – Recompensa: asset, valor, pontos, frequência e caps anti-fraude.
  7. Passo 4 – Vigência: datas, "exige usuário aprovado", nível mínimo.
  8. Salve. Para reaplicar a regra a eventos passados, use Recalcular.

Campos ​

CampoO que éObrigatório?Efeito no sistema/backend
Evento (event)Gatilho da missão (1 dos 28 do catálogo)SimDefine quando a missão é avaliada (ex.: DEPOSIT_CONFIRMED, ORDER_EXECUTED, USER_LOGIN_DAILY).
Condições (condition)Filtros específicos do eventoNãoJSON editável campo a campo (ex.: thresholdFiat, minAmountFiat, everyN, assetFilter). Restringe quando a missão paga.
Nome (name) / Código (code)Nome exibido e slug únicoSimO code é gerado por slug a partir do nome (na criação) e é estável entre replays — base da idempotência.
Ícone (icon)Ícone do cardNãoMaterial Icons; quick-picker com sugestões.
Asset de recompensa (rewardAssetId)Asset pago ao concluirSim no wizard (passo 3)Se vazio no modelo final, o payout usa o defaultRewardAsset do Programa.
Valor (rewardAmount)Quanto é pagoSimString BigNumber; o passo 3 exige > 0.
Pontos (missionPoints)Pontos concedidos ao concluirNãoInteiro ≥ 0 (default 0). Contam para o tier quando o Programa usa a métrica POINTS.
Frequência (frequency)Cadência de pagamentoSimONCE_PER_USER (1x na vida), ONCE_PER_DAY, ONCE_PER_MONTH, EVERY_N_OCCURRENCES (paga a cada N — exige everyN).
A cada N (everyN)N de ocorrências para pagarCondicionalObrigatório quando a frequência é EVERY_N_OCCURRENCES.
Máx. por usuário (maxPerUser)Teto absoluto por usuárioNãoundefined = ilimitado (ainda limitado pela frequência).
Cap anti-fraude/usuário/dia (maxPayoutsPerUserPerDay)Máx. de payouts em 24h por usuário nessa missãoNão0 = sem limite. Recomendado > 0 em missões event-driven que disparam repetidamente.
Vigência (activeFrom / activeTo)Janela de validade da missãoactiveFrom simFora da janela a missão não paga.
Exige usuário aprovado (requiresApprovedUser)Só paga usuário APPROVEDNão (default true)Quando ligado, o payout só ocorre para usuário com status === 'APPROVED'.
Nível mínimo (lockedUntilTier)Restringe a missão a um tier ou acimaNãoA missão só dispara para usuários que atingiram o tier indicado.
Ativa (isActive)Liga/desliga a missão—Toggle inline na listagem.

Ações e modais ​

  • Salvar (wizard): POST (nova) ou PUT (edição) em /v1/rewards-club/admin/missions. Exige step-up (senha + MFA). missionPoints é normalizado para inteiro ≥ 0.
  • Toggle ativa/inativa: PATCH .../missions/:id/toggle. Em erro, o toggle reverte.
  • Recalcular: POST .../missions/:id/recalculate. Pergunta se é para todos os usuários ou um userId específico, e mostra {evaluated, payoutsTriggered} ao final. Exige step-up (o interceptor responde ao challenge 428 automaticamente). É a ferramenta de recompute proativo: reavalia a missão contra eventos já capturados.

Regras de negócio / cuidados ​

Atenção

  • Missões event-driven que podem disparar muitas vezes devem ter maxPayoutsPerUserPerDay > 0 para conter abuso/bot.
  • O code é a âncora de idempotência — não troque o código de uma missão em produção, senão replays/recálculos podem duplicar concessões.
  • missionPoints só influencia o nível quando o Programa usa métrica POINTS. Em métrica financeira, os pontos são apenas informativos.

Irreversível

  • Recalcular pode disparar payouts reais retroativos. Revise o escopo (todos vs. um usuário) antes de confirmar; a operação concede recompensas de verdade.
  • Valores financeiros: rewardAmount é string BigNumber — sem arredondamento.
  • Idempotência: payouts via FinLib são idempotentes por externalId; o erro E00021 ("already processed") é sucesso (concessão já efetivada), não falha — por isso o recompute proativo é seguro contra duplicação.
  • Status APPROVED: com requiresApprovedUser ligado, só usuários aprovados recebem.

Exemplos ​

Cenário 1 — Primeira ordem paga em token (1x por usuário)
  1. Trigger: ORDER_EXECUTED.
  2. Identidade: "Primeira ordem" (code PRIMEIRA_ORDEM).
  3. Recompensa: asset tBRL, valor 5, missionPoints opcional.
  4. Frequência: ONCE_PER_USER.
  5. Vigência: a partir de hoje; requiresApprovedUser ligado.
  6. Salve (step-up). Cada usuário aprovado recebe uma vez na vida.
Cenário 2 — Login diário dá pontos (clube por pontos)
  1. Trigger: USER_LOGIN_DAILY.
  2. Recompensa: missionPoints = 50; valor monetário pode ser 0.
  3. Frequência: ONCE_PER_DAY; maxPayoutsPerUserPerDay = 1.
  4. Salve. Com Programa em métrica POINTS, os pontos alimentam o tier.
Cenário 3 — A cada 10 ordens, bônus
  1. Trigger: ORDER_EXECUTED, condição everyN: 10.
  2. Frequência: EVERY_N_OCCURRENCES, everyN = 10.
  3. Recompensa: asset + valor do bônus.
  4. Salve. A missão acumula ocorrências e paga a cada 10.

Telas relacionadas ​