Comisiones

Comisiones

Modelo

interface Commission {
  id: string;
  employee_id: string;
  period: string;           // "2026-Q1", "2026-05"
  commission_type: 'sales' | 'profit' | 'collection' | 'custom';
  calculation_base: 'revenue' | 'profit' | 'volume';
  rate: number;            // Porcentaje (ej: 5.0 = 5%)
  fixed_amount?: number;    // Cantidad fija adicional
  base_amount: number;     // Importe base sobre el que se calcula
  commission_amount: number;
  status: 'pending' | 'calculated' | 'approved' | 'paid';
  paid_at?: string;
  paid_payroll_id?: string;  // Vinculado a la nomina donde se pagó
  notes?: string;
  created_at: string;
}

Tipos de comision

Tipo	Descripcion
sales	Por ventas realizadas (facturado)
profit	Por beneficios generados (margen)
collection	Por cobros realizados (porcentaje de lo cobrado)
custom	Formula personalizada

Base de calculo

Base	Descripcion
revenue	Sobre el importe facturado (sin impuestos)
profit	Sobre el margen de beneficio del documento
volume	Sobre el numero de unidades vendidas

---

Endpoints

Metodo	Ruta	Descripcion
GET	/api/hr/commissions	Listar comisiones
POST	/api/hr/commissions	Crear comision
GET	/api/hr/commissions/:id	Ver comision
PATCH	/api/hr/commissions/:id	Editar comision
POST	/api/hr/commissions/:id/approve	Aprobar comision
POST	/api/hr/commissions/:id/mark-paid	Marcar como pagada
DELETE	/api/hr/commissions/:id	Eliminar comision

Crear comision

POST /api/hr/commissions
Authorization: Bearer <token>
Content-Type: application/json

{
  "employee_id": "emp_001",
  "period": "2026-Q1",
  "commission_type": "sales",
  "calculation_base": "revenue",
  "rate": 5.0,
  "fixed_amount": 100.00,
  "base_amount": 25000.00,
  "notes": "5% sobre facturacion + bono fijo de 100 EUR"
}

Respuesta:

{
  "data": {
    "id": "comm_001",
    "commission_amount": 1350.00,
    "calculation_detail": "5% de 25000.00 = 1250.00 + 100.00 fijo",
    "status": "calculated"
  }
}

Calcular comisiones automaticamente

POST /api/hr/commissions/calculate
Content-Type: application/json

{
  "period": "2026-Q1",
  "employee_ids": ["emp_001", "emp_002"],
  "calculation_base": "revenue"
}

Recorre todos los documentos facturados del periodo para cada empleado y calcula automaticamente las comisiones segun la tasa configurada.

Listar comisiones por empleado

GET /api/hr/commissions?employee_id=emp_001&status=pending

---

Vinculacion con nominas

Las comisiones aprobadas se pueden incluir automaticamente en la nomina del siguiente periodo:

POST /api/hr/commissions/:id/approve

Las comisiones aprobadas aparecen como concepto en la nomina del empleado:

{
  "concept_name": "Comision Q1 2026",
  "amount": 1350.00,
  "type": "earning"
}

---

Resumen de endpoints

Metodo	Ruta	Descripcion
GET	/api/hr/commissions	Listar comisiones
POST	/api/hr/commissions	Crear comision
POST	/api/hr/commissions/calculate	Calcular automaticamente
GET	/api/hr/commissions/:id	Ver comision
PATCH	/api/hr/commissions/:id	Editar comision
POST	/api/hr/commissions/:id/approve	Aprobar
POST	/api/hr/commissions/:id/mark-paid	Marcar como pagada