Documentação

Español

Português
English

Español

Português
English

Appearance

Club de Recompensas — Programa ​

Requisitos de acceso

  • Permiso (módulo): viewRewardsProgram (para leer) / manageRewardsProgram (para guardar)
  • Licencia/Feature: REWARDS_CLUB
  • Contenedor del menú: GENERAL → grupo Club de Recompensas

Qué es / cuándo usar ​

La pantalla Programa es el singleton de configuración del Club de Recompensas (RCS) para el tenant. Aquí defines la identidad del club, cómo se calcula el nivel (tier) del usuario (métrica + ventana), los caps anti-fraude globales, los pools de pago (carteras-casa por activo) y las cotizaciones manuales usadas cuando no hay price-feed automático.

Úsalo al montar el club por primera vez y siempre que necesites cambiar la regla macro (ej.: pasar de "volumen de depósitos" a "puntos de misión", pausar payouts en emergencia, abastecer/monitorear el pool de pago).

Requisitos previos ​

  • Permiso: viewRewardsProgram para abrir; manageRewardsProgram para que los controles queden editables y el Guardar funcione (permiso doble: enum CPM + módulo dinámico en la DB).
  • Licencia/Feature: REWARDS_CLUB habilitada en la licencia del tenant (Vault). Si está deshabilitada, el grupo ni siquiera aparece en el menú.
  • Dependencias de otras pantallas: los niveles se crean en Niveles y las misiones en Misiones. Cuando la métrica de nivel es POINTS, es necesario tener misiones que otorguen puntos.

Paso a paso ​

  1. Accede al menú Club de Recompensas → Programa (/rewards-club/program).
  2. Define el Estado (Activo/Pausado) y el nombre del programa.
  3. Elige la Métrica del nivel (volumen de depósitos, volumen negociado o puntos de misión) haciendo clic en el card correspondiente.
  4. Elige la Ventana del nivel (vitalicia, últimos 90 días o año corriente).
  5. Configura el activo predeterminado de recompensa y el fiat de referencia.
  6. Ajusta los caps anti-fraude (por día, por usuario/día).
  7. Registra los pools de pago (una cartera-casa por activo) y, si es necesario, las cotizaciones manuales.
  8. Haz clic en Guardar — la mutación requiere step-up (ver abajo).

Campos ​

CampoQué es¿Obligatorio?Efecto en el sistema/backend
Estado (status)ACTIVE o PAUSEDSíActivo: los eventos disparan payouts y el tier engine recomputa en ciclo. Pausado: los eventos continúan siendo auditados, pero las misiones no pagan; el tier engine sigue funcionando. Usa Pausado en emergencias.
Métrica del nivel (tierMetric)Cómo se calcula el nivelSíDEPOSIT_VOLUME (suma de depósitos confirmados en fiat), TRADE_VOLUME (volumen negociado en fiat) o POINTS (puntos de misión). Valores canónicos de rcs-lib — definen qué suma el engine para posicionar al usuario en un nivel.
Ventana del nivel (tierWindow)Período considerado en la métricaSíLIFETIME (acumulado vitalicio — nunca pierde el nivel), ROLLING_90D (ventana rodante de 90 días — puede perder el nivel), CALENDAR_YEAR (se resetea el 1 de enero).
Activo predeterminado de recompensa (defaultRewardAsset)Token/activo usado cuando la misión no define unoNoCuando una misión no tiene rewardAssetId, el payout usa este activo. Hace el token de recompensa configurable y modular (ej.: tBRL, MID, USDC) — sin atarlo al fiat.
Fiat de referencia (referenceFiat)Moneda de visualización de la métrica financieraCondicionalUsado para mostrar la métrica cuando es DEPOSIT_VOLUME/TRADE_VOLUME. Cuando la métrica es POINTS, la UI muestra en "pts" e ignora este campo. Reemplaza el fiatRef legado (reflejado para retrocompat).
Cap global por día (globalMaxPayoutsPerDay)Límite anti-bot de payouts/24h en todo el programaNo0 = sin límite.
Cap por usuario/día (globalMaxPayoutsPerUserPerDay)Límite anti-bot de payouts/24h por usuario (todas las misiones)No0 = sin límite. Capa de protección independiente del cap por misión.
Pools de pago (pools[])Carteras-casa que guardan el saldo de payout por activoSí (para pagar)Cada pool tiene assetId, walletAddress, balance (saldo) y minBalanceAlert (límite de alerta). La barra de saldo se pone roja cuando balance ≤ minBalanceAlert. Sin pool con saldo, el activo no puede pagar.
Cotizaciones manuales (manualQuotes)Override de cotización activo → fiat de referenciaNoMap ACTIVO → valor (1 unidad del activo = N de fiat). Usado por el QuoteService del RCS cuando no hay price-feed automático para ese par. Las líneas en blanco se ignoran al guardar.

El mapa NFTs por nivel (tierNftAssets) aparece aquí solo como lectura (retrocompat con programas legados). La generación del NFT de cada nivel se movió a la pantalla Niveles (botón "Generar NFT" por fila).

Acciones y modales ​

  • Guardar: persiste el programa via PUT /v1/rewards-club/admin/program. Requiere step-up (X-Step-Up-Token: re-autenticación contraseña + MFA, ventana de 5 min). Si el token expira, el gateway responde 428 Step-up required y el interceptor solicita nueva verificación.
  • Agregar/Eliminar pool y Agregar/Eliminar cotización manual: manipulan las listas localmente; solo se persisten al Guardar.

Reglas de negocio / precauciones ​

Atención

  • Pausar el programa no detiene la captura de eventos (la auditoría continúa) — solo suspende los pagos. Útil para contener un incidente sin perder el historial.
  • La elección entre LIFETIME y ventanas rodantes cambia profundamente el comportamiento: en LIFETIME el usuario nunca pierde el nivel; en ROLLING_90D/CALENDAR_YEAR puede perder el nivel.
  • Cambiar la métrica a POINTS sin misiones que otorguen puntos configuradas deja a todos en el nivel base. Asegúrate de tener misiones con missionPoints > 0 primero.
  • Mantén los pools abastecidos: un saldo por debajo de la alerta señala riesgo de que los payouts fallen por falta de fondos en la cartera-casa.
  • Valores financieros: saldos, alertas y cotizaciones se transmiten como string BigNumber — sin redondeo; trata como BigNumber antes de cualquier aritmética.
  • Idempotencia: los payouts subyacentes pasan por FinLib, que es idempotente por externalId. El código de error E00021 ("already processed") significa éxito (ya liquidado), no fallo.

Ejemplos ​

Escenario 1 — Club de captación por volumen de depósitos (vitalicio)

Objetivo: premiar a quienes más depositan, sin nunca degradar de nivel.

  1. Estado = Activo.
  2. Métrica = "Volumen de depósitos".
  3. Ventana = "Vitalicia".
  4. Fiat de referencia = BRL.
  5. Activo predeterminado de recompensa = tBRL.
  6. Registra un pool tBRL con la cartera-casa y un minBalanceAlert cómodo.
  7. Guarda (step-up). Los thresholds de cada nivel (en BRL) se definen en Niveles.
Escenario 2 — Club de engagement por puntos (rodante 90 días)

Objetivo: premiar la actividad continua; quien para, baja.

  1. Métrica = "Puntos de misión".
  2. Ventana = "Últimos 90 días".
  3. Crea misiones con missionPoints > 0 (login diario, streak, órdenes) en Misiones.
  4. En Niveles, los thresholds pasan a mostrarse en pts (no en fiat).
  5. Guarda (step-up).
Escenario 3 — Contener un incidente sin perder el historial

Sospecha de abuso/bot disparando payouts:

  1. Abre Programa y cambia el Estado a Pausado, guarda (step-up).
  2. Los eventos continúan siendo capturados y auditados, pero ninguna misión paga.
  3. Ajusta los caps anti-fraude (globalMaxPayoutsPerUserPerDay > 0) y revisa las misiones sospechosas.
  4. Vuelve el estado a Activo cuando sea seguro.

Pantallas relacionadas ​