Pular para o conteúdo principal

Comissões

🛂 Permissões: commission.view, commission.manage, commission.approve, commission.pay, commission.reports 📍 Caminho: Clientes & Vendas → Comissões

O módulo de comissões automatiza o cálculo do que cada vendedor ganha sobre cada pedido. Cobre dois cenários:

  1. Pedido criado pelo vendedor (B2B clássico) — comissão pela alíquota da regra do vendedor.
  2. Pedido fechado pela loja online com cupom de vendedor — comissão pelo cupom (por exemplo, parceria de influencer).

Conceitos​

CommissionRule (regra do vendedor)​

Define a alíquota padrão do vendedor (ex.: 5%). Uma regra por vendedor por tenant. Aplicada quando o pedido é criado diretamente por aquele vendedor (SELLER_ORDER).

CouponCommission (cupom vinculado a vendedor)​

Associa um cupom (Cupons de desconto) a um vendedor. Quando o cliente usa esse cupom no checkout, a comissão vai para o vendedor (COUPON). Pode sobrescrever a alíquota padrão.

Commission (registro)​

Imutável, gerado automaticamente após cada pedido qualificável. Base de cálculo:

base = total - delivery_fee - discount_amount
comissao = base × commission_rate

Fica vinculado ao pedido (order_id único — uma comissão por pedido).

Status do registro​

StatusSignificado
PENDINGPendente, aguardando aprovação.
APPROVEDAprovado para pagamento.
PAIDPago.
CANCELLEDCancelado (ex.: pedido cancelado).

A flag Aprovação obrigatória (commission_approval_required no tenant) controla se as comissões nascem em PENDING (precisam de aprovação) ou já em APPROVED.

Aba 1 — Regras (CommissionRules)​

Em Comissões → Regras:

  1. Clique em Nova Regra.
  2. Selecione o vendedor (usuário com role SELLER).
  3. Informe a alíquota (ex.: 5.00 = 5%).
  4. Marque como ativa.
  5. Salve.

Limite: uma regra por vendedor.

Aba 2 — Cupons (CouponCommissions)​

Em Comissões → Cupons:

  1. Clique em Vincular Cupom.
  2. Escolha o cupom (ver Cupons de desconto).
  3. Escolha o vendedor.
  4. (Opcional) Defina alíquota override — sobrescreve a regra padrão do vendedor para esse cupom.
    • Vazio = usa a alíquota da regra padrão.
  5. Marque como ativa.
  6. Salve.

Aba 3 — Registros (Commissions)​

Lista todas as comissões geradas. Filtros:

  • Por vendedor.
  • Por status.
  • Por período.
  • Por origem (SELLER_ORDER / COUPON).

Ações em massa:

  • Aprovar (permissão commission.approve)
  • Marcar como pago (permissão commission.pay)
  • Cancelar

Cada linha mostra: pedido, cliente, base, alíquota, valor da comissão, origem, status.

Aba 4 — Relatórios​

Permissão commission.reports. Mostra totais por vendedor por período (a pagar, pago, cancelado). Exporta para CSV/Excel.

Como o sistema decide a alíquota​

Ordem de prioridade ao gerar a comissão:

  1. Cupom usado no pedido tem CouponCommission ativa?
    • Sim → origem = COUPON, alíquota = override do cupom ou alíquota da regra do vendedor associado.
  2. Pedido foi criado por vendedor com CommissionRule ativa?
    • Sim → origem = SELLER_ORDER, alíquota = regra do vendedor.
  3. Caso contrário → nenhuma comissão é gerada.

Cancelamento de pedido​

Quando um pedido vira Canceled, a comissão associada é automaticamente marcada como CANCELLED. Não é restaurada se o pedido for "des-cancelado" — gere uma nova manualmente.

Boas práticas​

  • Defina a flag commission_approval_required se quer auditar comissões antes de pagar.
  • Use cupons vinculados para parceiros externos (influencers, indicadores) — o desconto sai no preço, a comissão aparece no relatório.
  • Audite o relatório antes de fechar o mês — confira contra os pedidos.
  • Pague via PIX em lote (a plataforma não automatiza o pagamento ao vendedor, só calcula).
  • Mantenha o cadastro do vendedor com dados bancários em campo de notas para facilitar o pagamento.