Comissões

Escopo: commissions:read nas duas rotas.

Escopo: commissions:read nas duas rotas.

GET/api/commissions/plans — lista os planos configurados (faixas, bônus, política de pagamento).

⛔ Esta rota é a exceção da convenção de listagem. Ela devolve { "data": [...] } sem o objeto pagination — não é null, é ausente. ⛒ Cliente genérico que faz resposta.pagination.next_cursor em toda listagem (que é o que a convenção do topo desta página instrui) quebra aqui. Trate pagination como opcional nesta rota.

POST/api/commissions/calculate — roda o motor de regras sobre os números que você manda:

{ "salesperson": "Maria Souza", "revenue": 62000, "deal_count": 8 }
Campo Obrigatório Regras
salesperson sim nome do vendedor (texto, até 200) — é por ele que o plano e a meta do vendedor são encontrados
revenue sim receita apurada, ≥ 0
deal_count sim quantidade de negócios, inteiro ≥ 0
base não base de cálculo alternativa; sem ela, usa o revenue
reference_date não AAAA-MM-DD, para validar bônus por período e escolher o mês da meta. Sem ela, vale o dia de hoje (Brasília)

Quando o vendedor tem meta do mês cadastrada em Metas (na mesma unidade do plano dele), o attainment é calculado contra ela — o mesmo que a tela de Comissões faz.

{
  "data": {
    "plan_id": "…",
    "plan_name": "Plano padrão",
    "rate": 0.04,
    "commission_amount": 2480,
    "bonus_amount": 500,
    "attainment": 1.24
  }
}

É uma calculadora, não um extrato. Ela simula sobre os números que você informa — não consulta vendas reais nem confirma pagamento.

Com a permissão "Só o dele" em Comissões, a chave só calcula para o próprio nome do responsável pela chave (§2); outro nome devolve 403. Não existe ensaio (dry_run) aqui — a rota não grava nada.