> ## 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.

# Empleados

> Consultar, crear y actualizar empleados

| Operación | Permiso |
| - | - |
| Consultar empleados y puestos | `hr.employees` |
| Crear y actualizar empleados | `hr.employees.write` |

<Warning>
  Este permiso expone datos personales y salarios. Protege la API Key y limita el acceso a sistemas de confianza.
</Warning>

## Listar empleados

```http theme={null}
GET /hr/employees
```

| Parámetro | Tipo | Descripción |
| - | - | - |
| `is_active` | boolean | Filtra activos (`1`) o inactivos (`0`). Sin el parámetro devuelve ambos. |
| `search` | string | Busca por nombre, apellido o correo. |
| `document_number` | string | Filtra por número de documento exacto. |
| `per_page` | integer | Resultados por página (1–200, por defecto 50). |
| `page` | integer | Página. |

```json theme={null}
{
  "status": true,
  "data": {
    "data": [
      {
        "id": "uuid",
        "first_name": "María",
        "last_name": "López",
        "document_type": "DUI",
        "document_number": "01234567-8",
        "tax_number": "0614-010190-101-1",
        "email": "maria@empresa.com",
        "phone": "7000-0000",
        "type": "permanent",
        "job_title": "Contadora",
        "hire_date": "2024-02-01",
        "salary": 850.00,
        "is_active": true
      }
    ],
    "pagination": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 }
  }
}
```

| Campo | Descripción |
| - | - |
| `type` | Tipo de contratación: `permanent`, `temporary` o `project_based`. |
| `salary` | Salario mensual. |
| `hire_date` | Fecha de ingreso. |

## Consultar empleado

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

Devuelve el mismo objeto de empleado. Los empleados eliminados responden `404`.

## Puestos de trabajo

```http theme={null}
GET /hr/job-titles
```

Devuelve el catálogo de puestos (`id`, `name`, `description`, `parent_id`) para obtener el `job_title_id`. Requiere `hr.employees`.

## Crear empleado

```http theme={null}
POST /hr/employees
```

**Permiso requerido:** `hr.employees.write`

```json theme={null}
{
  "first_name": "María",
  "last_name": "López",
  "document_type": "DUI",
  "document_number": "01234567-8",
  "tax_number": "0614-010190-101-1",
  "email": "maria@empresa.com",
  "phone": "7000-0000",
  "type": "permanent",
  "job_title_id": "uuid",
  "manager_id": "uuid",
  "hire_date": "2026-10-01",
  "salary": 850.00,
  "bank_name": "Banco Agrícola",
  "bank_account_type": "Ahorro",
  "bank_account_number": "3000123456"
}
```

| Campo | Requerido | Descripción |
| - | - | - |
| `first_name`, `last_name` | Sí | Nombres y apellidos. |
| `type` | Sí | `permanent`, `temporary` o `project_based`. |
| `hire_date` | Sí | Fecha de ingreso (`YYYY-MM-DD`). Se usa para antigüedad, aguinaldo, vacaciones y finiquito. |
| `salary` | Sí | Salario mensual. |
| `document_type`, `document_number` | No | Documento de identidad. El número debe ser **único** en el negocio: con él se identifican las marcaciones y permisos. |
| `tax_number` | No | NIT. |
| `email`, `phone`, `address` | No | Contacto. |
| `birth_date` | No | Fecha de nacimiento. |
| `job_title_id` | No | Puesto (`GET /hr/job-titles`). |
| `manager_id` | No | Jefe inmediato (ID de otro empleado). |
| `emergency_contact_name`, `emergency_contact_phone` | No | Contacto de emergencia. |
| `bank_name`, `bank_account_type`, `bank_account_number` | No | Cuenta para el pago de planilla. |
| `is_active` | No | Por defecto `true`. |

**Respuesta `201`**: el empleado creado (mismo formato que la consulta).

| Código | Causa |
| - | - |
| `409` | Ya existe un empleado con ese número de documento. La respuesta incluye su `employee_id`. |
| `422` | Validación: campos requeridos, puesto o jefe inexistentes en el negocio. |

## Actualizar empleado

```http theme={null}
PUT /hr/employees/{id}
```

**Permiso requerido:** `hr.employees.write`

Envía solo los campos que cambian; los demás se conservan. Acepta los mismos campos que la creación.

```json theme={null}
{ "salary": 950.00, "job_title_id": "uuid" }
```

Para dar de baja a un empleado envía `{ "is_active": false }`. La API no elimina empleados: así se conserva su historial de planillas. El cálculo de su liquidación se hace con el [finiquito](/docs/rrhh/finiquitos) en FileXpress.


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