Configuração de comissões
Pré-requisitos de acesso
- Permissão (módulo):
manageCommissions(a tela é visível comviewCommissionsOUmanageCommissions; para criar/excluir é necessário o módulo de gestão) - Licença/Feature: Nenhuma
- Contêiner do menu: GERAL → grupo Comissões e Recompensas
O que é / quando usar
Esta tela define a tabela de comissões multinível da plataforma: para cada nível da cadeia de indicação você registra um valor (em porcentagem) que será distribuído automaticamente quando um usuário-final executa uma ação geradora de comissão (depósito, compra, ordem etc.).
O modelo é em cascata: o nível 1 é o indicador direto do usuário que executou a ação; o nível 2 é quem indicou esse indicador; e assim por diante. Cada nível tem seu próprio percentual. Use esta tela quando precisar criar a estrutura de bonificação por indicação ou ajustar os percentuais de cada degrau.
Pré-condições
- Permissão:
manageCommissionscadastrado para a role do operador (lembrar: permissão é dupla — enum CPM no backend + módulo dinâmico no DB). Sem o módulo de gestão, a tela abre em modo leitura e os botões de criar/excluir não aparecem. - Licença/Feature: Nenhuma específica.
- Dependências de outras telas: a cadeia de indicação é formada quando usuários se cadastram usando o código de indicação de outro usuário. A configuração de níveis aqui só tem efeito prático se existirem cadeias de indicação reais.
Passo a passo
- Acesse o menu Comissões e Recompensas → Configuração de comissões (
/manage-commissions). - A tabela lista os níveis já configurados (ordenados pelo número do nível) com a coluna Nível e Valor.
- Clique em Novo para abrir o modal de criação de nível.
- Informe o Nível (inteiro ≥ 1) e o Valor (percentual > 0) e confirme.
- Para remover um nível, use o ícone de lixeira na linha correspondente e confirme no rodapé.
Campos
| Campo | O que é | Obrigatório? | Efeito no sistema/backend |
|---|---|---|---|
Nível (level_id) | Posição na cadeia de indicação (1 = indicador direto, 2 = indicador do indicador, …) | Sim | Chave da configuração no CustomerProfileService (CPM). É a PK lógica do nível — criar um nível já existente atualiza/colide; excluir usa este número. O modal valida level >= 1. |
Valor (amount) | Percentual da comissão pago aos usuários daquele nível | Sim | Percentual absoluto aplicado sobre a base de cálculo da operação geradora. O modal valida, via BigNumber, que o valor é maior que 0. Persistido como configuração de nível no CPM e consumido pelo motor de comissões multinível ao processar uma ação. |
Ações e modais
- Novo: abre o modal
Criar comissão. Exige Nível e Valor preenchidos; o botão de confirmar só habilita quandolevelestá definido eamount > 0(validação BigNumber). Ao salvar, chamacreateCommissionsConfiguratione recarrega a lista. - Excluir (lixeira): abre uma folha de confirmação (bottom-sheet). Confirmando, chama
deleteCommissionConfiguration(level_id)e recarrega a lista.
Regras de negócio / cuidados
Atenção
- O valor é um percentual, não um valor monetário fixo. Ele é aplicado sobre a base da operação que dispara a comissão.
- O número do nível é a identidade do registro: cadastrar um nível duplicado pode sobrescrever a configuração existente. Mantenha a sequência (1, 2, 3, …) sem buracos para que a cascata funcione como esperado.
- Esta tabela não paga comissões por si só — ela apenas define os percentuais. A geração efetiva acontece quando uma ação do usuário-final dispara o motor multinível; os lançamentos resultantes aparecem em Pagamento de comissões.
- Valores financeiros: o percentual e os valores derivados são tratados como BigNumber — sem arredondamento na interface; confira as casas decimais ao auditar pagamentos.
- Interação com o spread da casa: em operações de mercado, a comissão multinível convive com o spread/receita da casa. O custo da comissão deve ser dimensionado considerando a margem da operação para não comprometer a receita.