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.