Documentação

Español

Português
English

Español

Português
English

Appearance

Programa de Referencia ​

Requisitos de acceso

  • Permiso (módulo): viewIndicationProgram (para leer) / manageIndicationProgram (para crear/editar/eliminar)
  • Licencia/Feature: Ninguna
  • Contenedor del menú: GENERAL → grupo Programa de Referencia

Qué es / cuándo usarlo ​

Configura los programas de referencia (member-get-member): cuando alguien referido por un usuario realiza una acción cubierta (invertir en crowdfunding, ejecutar una orden, comprar en el marketplace, hacer staking, etc.), el referidor recibe una comisión. Usted define sobre qué se aplica la comisión (fee de la casa o monto bruto), el porcentaje, los eventos cubiertos y los topes por evento/mes.

El formulario incluye presets (Conservador, Equilibrado, Agresivo), un simulador en vivo y un resumen narrativo para validar la regla antes de guardar.

Requisitos previos ​

  • Permiso: viewIndicationProgram para leer; manageIndicationProgram para editar (permiso doble: enum CPM + módulo dinámico en la BD).
  • Licencia/Feature: Ninguna específica.
  • Dependencias de otras pantallas: las comisiones generadas por estos programas aparecen en Historial de comisiones de referencia.

Paso a paso ​

  1. Acceda al menú Programa de Referencia → Programas (/indication-program/programs).
  2. La lista muestra cada programa con eventos cubiertos y porcentaje. Haga clic en Nuevo o en un programa para editarlo (página independiente, no un drawer).
  3. (Opcional) Aplique un preset para pre-rellenar base, porcentaje, topes y eventos.
  4. Elija la base de cálculo (Sobre la fee de la casa / Sobre el monto bruto).
  5. Seleccione los eventos cubiertos (chips).
  6. Defina el porcentaje y, si lo desea, el tope por evento y el tope mensual.
  7. Use el simulador (monto bruto + fee%) para verificar la comisión resultante y lea el resumen narrativo.
  8. Guarde.

Campos ​

CampoQué es¿Obligatorio?Efecto en el sistema/backend
Nombre (name)Nombre del programaSíIdentifica el programa. Validado como no vacío.
Descripción (description)Texto libreNoSolo informativo.
Activo (isActive)Activa/desactiva el programa—Un programa inactivo no genera comisiones.
Base de cálculo (baseKind)Sobre qué se aplica el porcentajeSíSYSTEM_FEE = % de la fee que cobra la casa (sostenible: nunca paga más que la fee; recomendado). GROSS_AMOUNT = % del monto bruto de la operación (legacy; puede superar la fee y generar pérdida).
Eventos cubiertos (appliesTo[])Qué acciones disparan una comisiónSíLista de eventos (crowdfunding, orden, marketplace, NFT, staking, depósito…). Validado: al menos 1 evento.
Porcentaje (percent)% aplicado sobre la baseSíString BigNumber; validado > 0.
Tope por evento (maxPerEventFiat)Límite por comisión individualNoLimita el valor de cada comisión; aplicado en el cálculo (el simulador respeta el tope).
Tope mensual (maxPerMonthFiat)Límite mensual por referidorNoCada referidor recibe como máximo este monto/mes sumando todas las comisiones.
Moneda (unitOfMoney)Asset acreditado en la comisiónSí (default tBRL)Asset en que se paga la comisión.

Acciones y modales ​

  • Nuevo / Editar: página independiente (/indication-program/programs/new y /programs/:id/edit).
  • Aplicar preset: rellena base, porcentaje, topes y eventos a partir de la plantilla elegida (preserva nombre/descripción/activo).
  • Simulador: calcula vía BigNumber la comisión para un monto bruto y una fee% dados, respetando el tope por evento. El resumen narrativo describe la regla en lenguaje natural.
  • Guardar: upsertProgram en CustomerProfileService (CPM). Valida nombre, ≥ 1 evento y porcentaje > 0.
  • Eliminar: confirma y elimina el programa.

Reglas de negocio / precauciones ​

Atención

  • Prefiera la base SYSTEM_FEE: es sostenible porque la comisión nunca supera la fee cobrada. La base GROSS_AMOUNT es legacy y puede pagar más de lo que recibe la casa — úsela solo en campañas controladas.
  • El preset Agresivo intencionalmente no tiene tope mensual — está destinado a campañas de ventana limitada. No lo deje activo indefinidamente.
  • Todos los cálculos financieros usan BigNumber (porcentajes y topes como string) — no redondee al revisar.
  • Idempotencia: las comisiones generadas son liquidadas por FinLib (idempotente por externalId); el error E00021 ("already processed") es éxito.

Ejemplos ​

Escenario 1 — Programa sostenible (Equilibrado)
  1. Aplique el preset Equilibrado: base SYSTEM_FEE, porcentaje 25%, tope/evento 200, tope/mes 2000.
  2. Eventos: crowdfunding, orden ejecutada, marketplace, staking.
  3. Simulador: operación de R$ 1.000 con fee 2% → fee R$ 20 → comisión R$ 5 (25% de la fee).
  4. Guarde. El referidor recibe el 25% de la fee en tBRL, limitado por los topes.
Escenario 2 — Campaña de adquisición (Agresivo, ventana corta)
  1. Aplique Agresivo: base SYSTEM_FEE, porcentaje 50%, tope/evento 500, sin tope mensual.
  2. Eventos amplios (incluye depósito y NFT comprada).
  3. Manténgalo activo solo durante la campaña y desactívelo después.
Escenario 3 — Comisión sobre monto bruto (legacy, con cautela)
  1. Base GROSS_AMOUNT, porcentaje bajo (ej.: 1%), tope por evento obligatorio para limitar la exposición.
  2. Confirme en el simulador que la comisión no supera la fee de la operación típica.
  3. Guarde siendo consciente del riesgo de que la comisión supere el margen.

Pantallas relacionadas ​