Comissões — Endpoints

Base URL: /api/commissions

Permissões: Admin, Financial (CRUD), Broker (leitura das próprias)

---

GET /api/commissions

Lista comissões da empresa.

Query params:

Parâmetro	Tipo	Descrição
page	integer	Página (padrão: 1)
pageSize	integer	Itens por página
search	string	Busca por corretor ou contrato
status	string	Pending, Approved, Paid
brokerId	guid	Filtrar por corretor
contractId	guid	Filtrar por contrato

Resposta 200:

{
  "data": [
    {
      "id": "f1a2b3c4-...",
      "value": 2800.00,
      "percentage": null,
      "status": "Pending",
      "broker": {
        "id": "b1c2d3e4-...",
        "name": "Paulo Corretor"
      },
      "contract": {
        "id": "d1e2f3a4-...",
        "type": "Lease",
        "value": 2800.00
      },
      "createdAt": "2026-05-20T10:00:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 14,
  "totalPages": 1,
  "hasNext": false,
  "hasPrevious": false
}

---

GET /api/commissions/:id

Retorna detalhes de uma comissão.

Resposta 200:

{
  "id": "f1a2b3c4-...",
  "value": 2800.00,
  "percentage": null,
  "status": "Approved",
  "notes": "Equivalente a 1 mês de aluguel.",
  "broker": {
    "id": "b1c2d3e4-...",
    "name": "Paulo Corretor",
    "creci": "CRECI-SP 12345"
  },
  "contract": {
    "id": "d1e2f3a4-...",
    "type": "Lease",
    "value": 2800.00,
    "client": { "name": "João da Silva" },
    "property": { "code": "AP-001" }
  },
  "approvedAt": "2026-05-22T09:00:00Z",
  "paidAt": null,
  "createdAt": "2026-05-20T10:00:00Z"
}

---

POST /api/commissions

Registra uma comissão para um corretor.

Body:

{
  "brokerId": "b1c2d3e4-...",
  "contractId": "d1e2f3a4-...",
  "value": 2800.00,
  "percentage": null,
  "notes": "Comissão de 1 mês de aluguel"
}

Campo	Tipo	Obrigatório	Descrição
brokerId	guid	Sim	Corretor que receberá a comissão
contractId	guid	Sim	Contrato de origem
value	decimal	Condicional	Valor fixo
percentage	decimal	Condicional	Percentual sobre o valor do contrato

Preencher value ou percentage — não ambos.

Resposta 201: Comissão criada com status Pending.

---

PUT /api/commissions/:id

Atualiza dados da comissão.

---

PATCH /api/commissions/:id/status

Avança o status da comissão.

Permissões: Admin, Financial

Body:

{
  "status": "Approved",
  "notes": "Aprovado pelo financeiro."
}

Transições válidas:

Pending → Approved
Approved → Paid

Resposta 200: Comissão atualizada.

---

DELETE /api/commissions/:id

Remove comissão (soft delete).

Permissões: Admin

Erros:

• 400 — Comissão já foi paga