Documentação

Português

English
Español

Português

English
Español

Appearance

Programa de Indicação ​

Pré-requisitos de acesso

  • Permissão (módulo): viewIndicationProgram (para ler) / manageIndicationProgram (para criar/editar/excluir)
  • Licença/Feature: Nenhuma
  • Contêiner do menu: GERAL → grupo Programa de Indicação

O que é / quando usar ​

Configura os programas de indicação (member-get-member): quando alguém indicado por um usuário executa uma ação coberta (investir em crowdfunding, executar ordem, comprar no marketplace, fazer staking etc.), o indicador recebe uma comissão. Você define sobre o que a comissão incide (fee da casa ou valor bruto), o percentual, os eventos cobertos e tetos por evento/mês.

O formulário traz presets (Conservador, Equilibrado, Agressivo), um simulador ao vivo e um resumo narrativo para validar a regra antes de salvar.

Pré-condições ​

  • Permissão: viewIndicationProgram para ler; manageIndicationProgram para editar (permissão dupla: enum CPM + módulo dinâmico no DB).
  • Licença/Feature: Nenhuma específica.
  • Dependências de outras telas: as comissões geradas por estes programas aparecem em Histórico de comissões de indicação.

Passo a passo ​

  1. Acesse o menu Programa de Indicação → Programas (/indication-program/programs).
  2. A lista mostra cada programa com eventos cobertos e percentual. Clique em Novo ou em um programa para editar (página isolada, não drawer).
  3. (Opcional) Aplique um preset para pré-preencher base, percentual, tetos e eventos.
  4. Escolha a base de cálculo (Sobre a fee da casa / Sobre o valor bruto).
  5. Selecione os eventos cobertos (chips).
  6. Defina percentual e, se quiser, teto por evento e teto mensal.
  7. Use o simulador (valor bruto + fee%) para conferir a comissão resultante e leia o resumo narrativo.
  8. Salve.

Campos ​

CampoO que éObrigatório?Efeito no sistema/backend
Nome (name)Nome do programaSimIdentifica o programa. Validado como não-vazio.
Descrição (description)Texto livreNãoApenas informativo.
Ativo (isActive)Liga/desliga o programa—Programa inativo não gera comissões.
Base de cálculo (baseKind)Sobre o que o percentual incideSimSYSTEM_FEE = % da fee que a casa cobra (sustentável: nunca paga mais que a fee; recomendado). GROSS_AMOUNT = % do valor bruto da operação (legacy; pode exceder a fee e gerar prejuízo).
Eventos cobertos (appliesTo[])Quais ações disparam comissãoSimLista de eventos (crowdfunding, ordem, marketplace, NFT, staking, depósito…). Validado: ao menos 1 evento.
Percentual (percent)% aplicado sobre a baseSimString BigNumber; validado > 0.
Teto por evento (maxPerEventFiat)Limite por comissão individualNãoLimita o valor de cada comissão; aplicado no cálculo (o simulador respeita o teto).
Teto mensal (maxPerMonthFiat)Limite mensal por indicadorNãoCada indicador recebe no máximo este valor/mês somando todas as comissões.
Moeda (unitOfMoney)Asset creditado na comissãoSim (default tBRL)Asset em que a comissão é paga.

Ações e modais ​

  • Novo / Editar: página isolada (/indication-program/programs/new e /programs/:id/edit).
  • Aplicar preset: preenche base, percentual, tetos e eventos a partir do template escolhido (preserva nome/descrição/ativo).
  • Simulador: calcula via BigNumber a comissão para um valor bruto e uma fee% informados, respeitando o teto por evento. O resumo narrativo descreve a regra em português.
  • Salvar: upsertProgram no CustomerProfileService (CPM). Valida nome, ≥ 1 evento e percentual > 0.
  • Excluir: confirma e remove o programa.

Regras de negócio / cuidados ​

Atenção

  • Prefira a base SYSTEM_FEE: ela é sustentável porque a comissão nunca ultrapassa a fee cobrada. A base GROSS_AMOUNT é legacy e pode pagar mais do que a casa recebe — use só em campanhas controladas.
  • O preset Agressivo propositalmente não tem teto mensal — destina-se a campanhas por janela limitada. Não deixe ativo indefinidamente.
  • O cálculo financeiro é todo em BigNumber (percentuais e tetos como string) — não arredonde na conferência.
  • Idempotência: as comissões geradas são liquidadas pela FinLib (idempotente por externalId); o erro E00021 ("already processed") é sucesso.

Exemplos ​

Cenário 1 — Programa sustentável (Equilibrado)
  1. Aplique o preset Equilibrado: base SYSTEM_FEE, percentual 25%, teto/evento 200, teto/mês 2000.
  2. Eventos: crowdfunding, ordem executada, marketplace, staking.
  3. Simulador: operação de R$ 1.000 com fee 2% → fee R$ 20 → comissão R$ 5 (25% da fee).
  4. Salve. O indicador recebe 25% da fee em tBRL, limitado aos tetos.
Cenário 2 — Campanha de aquisição (Agressivo, janela curta)
  1. Aplique Agressivo: base SYSTEM_FEE, percentual 50%, teto/evento 500, sem teto mensal.
  2. Eventos amplos (inclui depósito e NFT comprada).
  3. Mantenha ativo apenas durante a campanha e desligue depois.
Cenário 3 — Comissão sobre valor bruto (legacy, com cautela)
  1. Base GROSS_AMOUNT, percentual baixo (ex.: 1%), teto por evento obrigatório para limitar exposição.
  2. Confirme no simulador que a comissão não excede a fee da operação típica.
  3. Salve cientes do risco de a comissão superar a margem.

Telas relacionadas ​