Documentação

Español

Português
English

Español

Português
English

Appearance

Club de Recompensas — Misiones ​

Requisitos de acceso

  • Permiso (módulo): viewRewardsProgram (para leer) / manageRewardsMissions (para crear/editar/activar/recalcular)
  • Licencia/Feature: REWARDS_CLUB
  • Contenedor del menú: GENERAL → grupo Club de Recompensas

Qué es / cuándo usar ​

Gestiona las misiones del club: reglas orientadas a eventos que, cuando se cumplen, otorgan una recompensa (activo + valor) y/o puntos. El listado es en cards con filtros por estado, frecuencia y evento; la creación/edición usa un wizard de 4 pasos (Trigger → Identidad → Recompensa → Vigencia).

Úsalo para diseñar la gamificación: "primera orden paga X", "login diario da Y puntos", "invertir en crowdfunding da Z", etc. El catálogo cubre 28 eventos soportados, agrupados por categoría (Financiero, Registro & KYC, Referido, Crowdfunding, Marketplace & NFT, Staking, Volumen & Streak, Cambio de Nivel).

Pre-condiciones ​

  • Permiso: viewRewardsProgram para leer; manageRewardsMissions para editar (permiso doble: enum CPM + módulo dinámico en la DB).
  • Licencia/Feature: REWARDS_CLUB.
  • Dependencias de otras pantallas: el activo de recompensa debe existir; si la misión no define uno, el payout usa el activo predeterminado del Programa. Para que las misiones con missionPoints cuenten para el nivel, el Programa debe usar la métrica POINTS.

Paso a paso ​

  1. Accede al menú Club de Recompensas → Misiones (/rewards-club/missions).
  2. Filtra por estado (todas/activas/inactivas), frecuencia, evento o texto libre.
  3. Haz clic en Nuevo para abrir el wizard.
  4. Paso 1 – Trigger: elige el evento en el catálogo (tabs por grupo + cards explicativos). Aplica ejemplos de condition_json o edita las condiciones campo a campo.
  5. Paso 2 – Identidad: nombre (genera el code/slug automáticamente), descripción, ícono.
  6. Paso 3 – Recompensa: activo, valor, puntos, frecuencia y caps anti-fraude.
  7. Paso 4 – Vigencia: fechas, "requiere usuario aprobado", nivel mínimo.
  8. Guarda. Para reaplicar la regla a eventos pasados, usa Recalcular.

Campos ​

CampoQué es¿Obligatorio?Efecto en el sistema/backend
Evento (event)Disparador de la misión (1 de los 28 del catálogo)SíDefine cuándo se evalúa la misión (ej.: DEPOSIT_CONFIRMED, ORDER_EXECUTED, USER_LOGIN_DAILY).
Condiciones (condition)Filtros específicos del eventoNoJSON editable campo a campo (ej.: thresholdFiat, minAmountFiat, everyN, assetFilter). Restringe cuándo la misión paga.
Nombre (name) / Código (code)Nombre mostrado y slug únicoSíEl code se genera como slug a partir del nombre (en la creación) y es estable entre replays — base de la idempotencia.
Ícono (icon)Ícono del cardNoMaterial Icons; quick-picker con sugerencias.
Activo de recompensa (rewardAssetId)Activo pagado al completarSí en el wizard (paso 3)Si está vacío en el modelo final, el payout usa el defaultRewardAsset del Programa.
Valor (rewardAmount)Cuánto se pagaSíString BigNumber; el paso 3 exige > 0.
Puntos (missionPoints)Puntos otorgados al completarNoEntero ≥ 0 (default 0). Cuentan para el nivel cuando el Programa usa la métrica POINTS.
Frecuencia (frequency)Cadencia de pagoSíONCE_PER_USER (1x en la vida), ONCE_PER_DAY, ONCE_PER_MONTH, EVERY_N_OCCURRENCES (paga cada N — requiere everyN).
Cada N (everyN)N de ocurrencias para pagarCondicionalObligatorio cuando la frecuencia es EVERY_N_OCCURRENCES.
Máx. por usuario (maxPerUser)Techo absoluto por usuarioNoundefined = ilimitado (aún limitado por la frecuencia).
Cap anti-fraude/usuario/día (maxPayoutsPerUserPerDay)Máx. de payouts en 24h por usuario en esta misiónNo0 = sin límite. Recomendado > 0 en misiones event-driven que se disparan repetidamente.
Vigencia (activeFrom / activeTo)Ventana de validez de la misiónactiveFrom síFuera de la ventana la misión no paga.
Requiere usuario aprobado (requiresApprovedUser)Solo paga usuarios APPROVEDNo (default true)Cuando está activado, el payout solo ocurre para usuarios con status === 'APPROVED'.
Nivel mínimo (lockedUntilTier)Restringe la misión a un nivel o superiorNoLa misión solo se dispara para usuarios que hayan alcanzado el nivel indicado.
Activa (isActive)Activa/desactiva la misión—Toggle inline en el listado.

Acciones y modales ​

  • Guardar (wizard): POST (nueva) o PUT (edición) en /v1/rewards-club/admin/missions. Requiere step-up (contraseña + MFA). missionPoints se normaliza a entero ≥ 0.
  • Toggle activa/inactiva: PATCH .../missions/:id/toggle. En error, el toggle se revierte.
  • Recalcular: POST .../missions/:id/recalculate. Pregunta si es para todos los usuarios o un userId específico, y muestra {evaluated, payoutsTriggered} al final. Requiere step-up (el interceptor responde al challenge 428 automáticamente). Es la herramienta de recompute proactivo: reevalúa la misión contra eventos ya capturados.

Reglas de negocio / precauciones ​

Atención

  • Las misiones event-driven que pueden dispararse muchas veces deben tener maxPayoutsPerUserPerDay > 0 para contener abuso/bot.
  • El code es el ancla de idempotencia — no cambies el código de una misión en producción, pues los replays/recálculos pueden duplicar concesiones.
  • missionPoints solo influye en el nivel cuando el Programa usa la métrica POINTS. Con métrica financiera, los puntos son solo informativos.

Irreversible

  • Recalcular puede disparar payouts reales retroactivos. Revisa el alcance (todos vs. un usuario) antes de confirmar; la operación otorga recompensas reales.
  • Valores financieros: rewardAmount es un string BigNumber — sin redondeo.
  • Idempotencia: los payouts vía FinLib son idempotentes por externalId; el error E00021 ("already processed") es éxito (concesión ya aplicada), no fallo — por eso el recompute proactivo es seguro contra duplicación.
  • Estado APPROVED: con requiresApprovedUser activado, solo los usuarios aprobados reciben.

Ejemplos ​

Escenario 1 — Primera orden pagada en token (1x por usuario)
  1. Trigger: ORDER_EXECUTED.
  2. Identidad: "Primera orden" (code PRIMERA_ORDEN).
  3. Recompensa: activo tBRL, valor 5, missionPoints opcional.
  4. Frecuencia: ONCE_PER_USER.
  5. Vigencia: a partir de hoy; requiresApprovedUser activado.
  6. Guarda (step-up). Cada usuario aprobado lo recibe una vez en la vida.
Escenario 2 — Login diario da puntos (club por puntos)
  1. Trigger: USER_LOGIN_DAILY.
  2. Recompensa: missionPoints = 50; el valor monetario puede ser 0.
  3. Frecuencia: ONCE_PER_DAY; maxPayoutsPerUserPerDay = 1.
  4. Guarda. Con el Programa en métrica POINTS, los puntos alimentan el nivel.
Escenario 3 — Cada 10 órdenes, bono
  1. Trigger: ORDER_EXECUTED, condición everyN: 10.
  2. Frecuencia: EVERY_N_OCCURRENCES, everyN = 10.
  3. Recompensa: activo + valor del bono.
  4. Guarda. La misión acumula ocurrencias y paga cada 10.

Pantallas relacionadas ​