Empleados

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

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

Listar empleados

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.

{
  "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

GET /hr/employees/{id}

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

Puestos de trabajo

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

POST /hr/employees

Permiso requerido: hr.employees.write

{
  "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

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.

{ "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 en FileXpress.

Primeros Pasos

Facturación

Recursos Humanos

Contabilidad

Referencia interactiva

Listar empleados

Consultar empleado

Puestos de trabajo

Crear empleado

Actualizar empleado

​Listar empleados

​Consultar empleado

​Puestos de trabajo

​Crear empleado

​Actualizar empleado

Listar empleados

Consultar empleado

Puestos de trabajo

Crear empleado

Actualizar empleado