Distribución (Dividendos)
Requisitos previos de acceso
- Permiso (módulo):
manageDividends(para crear, aprobar y eliminar distribuciones). La visualización del listado se habilita con acceso al grupo Inversiones. - Licencia/Feature: Ninguna específica.
- Contenedor del menú: GENERAL → grupo Inversiones / Distribuciones Financieras
Qué es / cuándo usar
La Distribución es el mecanismo de pago de ganancias (dividendos/rendimientos) a los tenedores de un token o de un NFT. El operador elige el activo cuyos tenedores recibirán el pago (un token o un NFT), define el token a distribuir, el monto total y los porcentajes, y el sistema genera la lista de pagos proporcional a la posición de cada holder.
La distribución se crea en estado AWAITING_APPROVAL y solo se ejecuta tras una aprobación explícita. Use esta pantalla para crear nuevas distribuciones, revisar el prorrateo generado, aprobar (liberar el pago) o eliminar (descartar antes de aprobar).
Requisitos previos
- Permiso:
manageDividendspara crear/aprobar/eliminar (doble — enum CPM en el backend + módulo en la BD). Sin él, las acciones de aprobar/eliminar no aparecen en el menú contextual de la fila. - Dependencias: el activo (token o NFT) ya debe existir y tener tenedores; el token usado como medio de pago debe estar registrado.
Paso a paso
- Acceda a Inversiones → Distribución (ruta
/manage-distributions). - Haga clic en Crear para abrir el modal de distribución.
- Elija la pestaña Por tokens o Por NFTs, seleccione el activo considerado (tenedores), el token a distribuir, ingrese el monto total y los porcentajes.
- Haga clic en Generar para previsualizar el prorrateo por usuario; ajuste valores individuales si es necesario.
- Confirme para guardar la distribución en
AWAITING_APPROVAL. - De vuelta en el listado, en el menú de acciones (
⋮) de la distribución, use Aprobar para liberar el pago.
Campos (modal de creación)
| Campo | Qué es | ¿Obligatorio? | Efecto en el sistema/backend |
|---|---|---|---|
| Pestaña (Por tokens / Por NFTs) | Define si los destinatarios son tenedores de un token o de un NFT | Sí | Establece token_id (tokens) o nft_id (NFTs) en el payload |
| Activo considerado | El token/NFT cuyos tenedores recibirán el pago | Sí | token_id/nft_id; debe ser validado (seleccionado de la lista) — un campo libre no validado bloquea el envío |
| Token a distribuir | El token usado como medio de pago de las ganancias | Sí | token_to_distribute |
| Monto total a distribuir | Monto total de las ganancias | Sí | total_to_distribute; debe ser > 0 |
| Porcentaje a distribuir | Porcentaje aplicado sobre la base | No | percentage_to_distribute; si se completa, debe ser ≥ 0 |
| Porcentaje para la red | Porción destinada a la red (solo pestaña tokens) | No | percentage_to_network; solo existe en la pestaña Por tokens |
En el paso de previsualización, cada destinatario aparece con nombre, correo electrónico y el monto individual, editable. La suma de los montos individuales no puede superar el total (exceedsTotal bloquea la confirmación).
Filtros y columnas (listado)
| Filtro / Columna | Qué muestra | Origen del dato |
|---|---|---|
| Búsqueda por nombre del activo | Filtra por assetName | Parámetro assetName |
| Orden | Más nuevos / más antiguos | order (newest/oldest) |
| Token | Filtra por el token considerado | token |
| Estado | AWAITING_APPROVAL, PROCESSED, APPROVED, CANCELLED | status |
| Tipo | Todos / Token / NFT | type |
| Fecha | Fecha de la solicitud | request_date |
| Token a distribuir | Medio de pago | token_to_distribute |
| Cantidad | Total a distribuir | total_to_distribute |
| Activo considerado | Nombre del activo | assetName |
| Estado (columna) | Estado actual; PROCESSED en verde, CANCELED en rojo | status |
Acciones y modales
- Crear: abre el modal de distribución (generación + previsualización). Guarda mediante
createDistributionRequestenAWAITING_APPROVAL. - Ver (
⋮ → Ver): abre el detalle de la distribución con la lista de pagos y cuántos ya fueron aplicados (applied). - Aprobar (
⋮ → Aprobar): disponible solo cuandostatus === AWAITING_APPROVALy con permisomanageDividends. Confirma en un bottom-sheet y llama aconfirmDistributionRequest— libera la ejecución de los pagos. - Eliminar (
⋮ → Eliminar): disponible solo enAWAITING_APPROVALy conmanageDividends. Descarta la distribución mediantedeleteDistributionRequest.
Reglas de negocio / consideraciones
Atención
- La suma de los montos individuales en el prorrateo no puede superar el total a distribuir; la confirmación queda bloqueada (
exceedsTotal). - Aprobar y Eliminar solo existen mientras la distribución está en
AWAITING_APPROVAL. Una vez aprobada/procesada, esas acciones ya no aparecen en la fila. - El porcentaje para la red solo se aplica a la distribución por tokens — no aparece para NFTs.
Irreversible
- La aprobación libera el pago de las ganancias a los holders. Una vez aprobada, la distribución no puede deshacerse desde la pantalla — revise el prorrateo antes de confirmar.
- Valores financieros:
total_to_distribute, montos individuales y porcentajes se tratan como BigNumber (hasta 8 decimales,ROUND_DOWN) — sin redondeo indebido. - Idempotencia: la ejecución financiera en FIN es idempotente por
externalId. Si un pago devuelveE00021("already processed"), significa éxito (ya acreditado), no un error — reprocesar es seguro. - NFTs de crowdfunding: la distribución paga ganancias, no emite ni quema NFTs. Para activos originados en crowdfunding, la emisión/quema de cuotas es exclusiva del job de crowdfunding — la distribución solo acredita el token de pago a los tenedores.
Ejemplos
Escenario 1 — Distribuir utilidades a tenedores de un token de participación
La empresa registró utilidades y quiere pagar ganancias a quienes poseen el token EMPX. Haga clic en Crear, pestaña Por tokens, establezca EMPX como activo considerado, elija el token de pago (ej.: tBRL), ingrese el monto total y el porcentaje deseado. Genere el prorrateo, revise los valores por holder y guarde en AWAITING_APPROVAL. Luego apruebe desde el listado para liberar los pagos.
Escenario 2 — Ganancias para tenedores de una colección de NFT
Un NFT de participación distribuye rendimiento periódico. Haga clic en Crear, pestaña Por NFTs, seleccione el NFT, el token de pago y el monto total. Note que el porcentaje para la red no aparece en esta pestaña. Genere, revise y guarde; luego apruebe. La distribución acredita el token a los propietarios — no modifica la cantidad de NFTs.
Escenario 3 — Ajuste manual de un destinatario en el prorrateo
Tras generar el prorrateo, un holder específico necesita recibir un monto diferente al proporcional (ej.: acuerdo puntual). En el paso de previsualización, edite el valor de esa fila. El sistema recalcula el restante y bloquea la confirmación si la suma supera el total. Ajuste hasta que la suma quepa en el total y confirme.