Distribuição (Dividendos)
Pré-requisitos de acesso
- Permissão (módulo):
manageDividends(para criar, aprovar e excluir distribuições). A visualização da listagem é liberada com acesso ao grupo Investimentos. - Licença/Feature: Nenhuma específica.
- Contêiner do menu: GERAL → grupo Investimentos / Distribuições Financeiras
O que é / quando usar
A Distribuição é o mecanismo de pagamento de proventos (dividendos/rendimentos) aos detentores de um token ou de uma NFT. O operador escolhe o ativo cujos detentores receberão (um token ou uma NFT), define o token a distribuir, o valor total e os percentuais, e o sistema gera a lista de pagamentos proporcional à posição de cada holder.
A distribuição é criada em estado AWAITING_APPROVAL e só executa após aprovação explícita. Use esta tela para criar novas distribuições, revisar o rateio gerado, aprovar (liberar o pagamento) ou excluir (descartar antes de aprovar).
Pré-condições
- Permissão:
manageDividendspara criar/aprovar/excluir (dupla — enum CPM no backend + módulo no DB). Sem ela, as ações de aprovar/excluir nem aparecem no menu de contexto da linha. - Dependências: o ativo (token ou NFT) já precisa existir e ter detentores; o token usado como meio de pagamento precisa estar cadastrado.
Passo a passo
- Acesse Investimentos → Distribuição (rota
/manage-distributions). - Clique em Criar para abrir o modal de distribuição.
- Escolha a aba Por tokens ou Por NFTs, selecione o ativo considerado (detentores), o token a distribuir, informe o valor total e os percentuais.
- Clique em Gerar para pré-visualizar o rateio por usuário; ajuste valores individuais se necessário.
- Confirme para salvar a distribuição em
AWAITING_APPROVAL. - De volta à lista, no menu de ações (
⋮) da distribuição, use Aprovar para liberar o pagamento.
Campos (modal de criação)
| Campo | O que é | Obrigatório? | Efeito no sistema/backend |
|---|---|---|---|
| Aba (Por tokens / Por NFTs) | Define se os destinatários são detentores de um token ou de uma NFT | Sim | Define token_id (tokens) ou nft_id (NFTs) no payload |
| Ativo considerado | O token/NFT cujos detentores receberão | Sim | token_id/nft_id; precisa ser validado (selecionado da lista) — campo livre não validado bloqueia o envio |
| Token a distribuir | O token usado como meio de pagamento dos proventos | Sim | token_to_distribute |
| Valor total a distribuir | Montante total do provento | Sim | total_to_distribute; deve ser > 0 |
| Percentual a distribuir | Percentual aplicado sobre a base | Não | percentage_to_distribute; se preenchido, deve ser ≥ 0 |
| Percentual para a rede | Parcela destinada à rede (somente aba tokens) | Não | percentage_to_network; só existe na aba Por tokens |
No passo de pré-visualização, cada destinatário aparece com nome, e-mail e o valor individual, editável. A soma dos valores individuais não pode exceder o total (exceedsTotal bloqueia a confirmação).
Filtros e colunas (listagem)
| Filtro / Coluna | O que mostra | Origem do dado |
|---|---|---|
| Busca por nome do ativo | Filtra pelo assetName | Parâmetro assetName |
| Ordem | Mais novos / mais antigos | order (newest/oldest) |
| Token | Filtra pelo token considerado | token |
| Status | AWAITING_APPROVAL, PROCESSED, APPROVED, CANCELLED | status |
| Tipo | Todos / Token / NFT | type |
| Data | Data da requisição | request_date |
| Token para distribuir | Meio de pagamento | token_to_distribute |
| Quantidade | Total a distribuir | total_to_distribute |
| Ativo considerado | Nome do ativo | assetName |
| Status (coluna) | Estado atual; PROCESSED em verde, CANCELED em vermelho | status |
Ações e modais
- Criar: abre o modal de distribuição (geração + pré-visualização). Salva via
createDistributionRequestemAWAITING_APPROVAL. - Visualizar (
⋮ → Ver): abre o detalhe da distribuição com a lista de pagamentos e quantos já foram aplicados (applied). - Aprovar (
⋮ → Aprovar): disponível apenas quandostatus === AWAITING_APPROVALe com permissãomanageDividends. Confirma em bottom-sheet e chamaconfirmDistributionRequest— libera a execução dos pagamentos. - Excluir (
⋮ → Excluir): disponível apenas emAWAITING_APPROVALe commanageDividends. Descarta a distribuição viadeleteDistributionRequest.
Regras de negócio / cuidados
Atenção
- A soma dos valores individuais no rateio não pode ultrapassar o total a distribuir; a confirmação fica bloqueada (
exceedsTotal). - Aprovar e Excluir só existem enquanto a distribuição está em
AWAITING_APPROVAL. Depois de aprovada/processada, não há mais essas ações na linha. - O percentual para a rede só se aplica à distribuição por tokens — não aparece para NFTs.
Irreversível
- A aprovação libera o pagamento dos proventos aos holders. Após aprovada, a distribuição não pode ser desfeita pela tela — revise o rateio antes de confirmar.
- Valores financeiros:
total_to_distribute, valores individuais e percentuais são tratados como BigNumber (até 8 casas,ROUND_DOWN) — sem arredondamento indevido. - Idempotência: a execução financeira no FIN é idempotente por
externalId. Se um pagamento retornarE00021("already processed"), isso significa sucesso (já creditado), não falha — reprocessar é seguro. - NFTs de crowdfunding: a distribuição paga proventos, ela não emite nem queima NFT. Para ativos originados de crowdfunding, a emissão/queima de cotas é exclusiva do job de crowdfunding — a distribuição apenas credita o token de pagamento aos detentores.
Exemplos
Cenário 1 — Distribuir lucro a detentores de um token de participação
A empresa apurou lucro e quer pagar proventos a quem detém o token EMPX. Clique em Criar, aba Por tokens, ative EMPX como ativo considerado, escolha o token de pagamento (ex.: tBRL), informe o valor total e o percentual desejado. Gere o rateio, revise os valores por holder e salve em AWAITING_APPROVAL. Depois aprove pela lista para liberar os pagamentos.
Cenário 2 — Provento a detentores de uma coleção de NFT
Uma NFT de participação distribui rendimento periódico. Clique em Criar, aba Por NFTs, selecione a NFT, o token de pagamento e o valor total. Repare que o percentual para a rede não aparece nesta aba. Gere, revise e salve; aprove em seguida. A distribuição credita o token aos donos — não muda a quantidade de NFTs.
Cenário 3 — Ajuste manual de um destinatário no rateio
Após gerar o rateio, um holder específico precisa receber um valor diferente do proporcional (ex.: acordo pontual). No passo de pré-visualização, edite o valor daquela linha. O sistema recalcula o restante e bloqueia a confirmação se a soma exceder o total. Ajuste até a soma caber no total e confirme.