> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Planillas

> Consultar planillas procesadas y su detalle por empleado

**Permiso requerido:** `hr.payrolls`

Solo se exponen planillas **procesadas** o **pagadas**. Los borradores (que aún pueden cambiar) y las planillas canceladas no se devuelven.

## Listar planillas

```http theme={null}
GET /hr/payrolls?start_date=2026-01-01&end_date=2026-12-31
```

| Parámetro | Requerido | Descripción |
| - | - | - |
| `start_date`, `end_date` | Sí | Devuelve las planillas cuyo período se cruza con el rango (máximo 370 días). |
| `status` | No | `processed` o `paid`. |

```json theme={null}
{
  "status": true,
  "data": [
    {
      "id": "uuid",
      "name": "Primera quincena octubre 2026",
      "start_date": "2026-10-01",
      "end_date": "2026-10-15",
      "status": "paid",
      "employees": 12,
      "total_net_amount": 4820.35
    }
  ]
}
```

## Detalle de una planilla

```http theme={null}
GET /hr/payrolls/{id}
```

```json theme={null}
{
  "status": true,
  "data": {
    "id": "uuid",
    "name": "Primera quincena octubre 2026",
    "start_date": "2026-10-01",
    "end_date": "2026-10-15",
    "status": "paid",
    "total_net_amount": 4820.35,
    "details": [
      {
        "employee_id": "uuid",
        "employee_name": "María López",
        "document_number": "01234567-8",
        "net_amount": 371.29,
        "payment_status": "paid",
        "payment_date": "2026-10-15",
        "earnings": [
          { "name": "Horas extra", "concept": "overtime", "quantity": 4, "amount": 28.33 }
        ],
        "deductions": [
          { "name": "ISSS Laboral", "concept": "policy", "quantity": null, "amount": 13.60 },
          { "name": "AFP Laboral", "concept": "policy", "quantity": null, "amount": 32.86 },
          { "name": "Inasistencias", "concept": "absence", "quantity": 1, "amount": 28.33 },
          { "name": "Renta (ISR)", "concept": "income_tax", "quantity": null, "amount": 1.95 }
        ],
        "employer_contributions": [
          { "name": "ISSS Patronal", "concept": "policy", "quantity": null, "amount": 34.00 },
          { "name": "AFP Patronal", "concept": "policy", "quantity": null, "amount": 39.66 }
        ]
      }
    ]
  }
}
```

| Campo | Descripción |
| - | - |
| `net_amount` | Neto a pagar al empleado. |
| `earnings` | Ingresos adicionales al salario del período (horas extra, bonificaciones). |
| `deductions` | Retenciones y descuentos (cotizaciones, renta, inasistencias, permisos sin goce). |
| `employer_contributions` | Aportes del patrono. **No** afectan el neto del empleado. |
| `concept` | `policy` (política de planilla), `income_tax` (renta), `absence` (inasistencias), `unpaid_leave` (permisos sin goce) u `overtime` (horas extra). Puede ser `null` en planillas antiguas. |
| `quantity` | Días de inasistencia u horas extra, según el concepto. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.