Overview The Employees API allows you to manage employee records within your organization. Employees are authenticated users with specific roles (cargos) and department assignments (dependencias). This API handles CRUD operations, authentication, status management, and various filtering capabilities.
The Employee Object Unique identifier for the employee
Employee’s first name (max 120 characters)
Employee’s last name (max 120 characters)
Employee’s email address (max 150 characters, must be unique)
Employee’s phone number (max 30 characters)
Foreign key reference to the employee’s position/role
Foreign key reference to the employee’s department
Employee’s active status (true = active, false = inactive)
Related position object with details about the employee’s role Related department object with details about the employee’s department Show dependencia properties
Timestamp when the employee was created
Timestamp when the employee was last updated
List All Employees This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
Returns a list of all employees with their related cargo and dependencia information.
Response { "success" : true , "data" : [ { "id_empleado" : 1 , "nombre" : "Juan" , "apellido" : "Pérez" , "email" : "[email protected] " , "telefono" : "+57 300 123 4567" , "id_cargo" : 1 , "id_dependencia" : 1 , "estado" : true , "cargo" : { "id_cargo" : 1 , "nombre" : "Gerente de Proyectos" , "descripcion" : "Responsable de la gestión de proyectos" }, "dependencia" : { "id_dependencia" : 1 , "nombre" : "Proyectos" , "descripcion" : "Departamento de gestión de proyectos" }, "created_at" : "2024-01-15T10:30:00.000000Z" , "updated_at" : "2024-01-15T10:30:00.000000Z" } ] }
Create Employee This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
Creates a new employee record with authentication credentials.
Body Parameters Employee’s first name (max 120 characters)
Employee’s last name (max 120 characters)
Employee’s email address (max 150 characters, must be unique)
Employee’s password (minimum 6 characters, will be hashed)
Employee’s phone number (max 30 characters)
Position ID that must exist in the cargo table
Department ID that must exist in the dependencia table
Request Example { "nombre" : "María" , "apellido" : "González" , "email" : "[email protected] " , "password" : "SecurePass123" , "telefono" : "+57 301 234 5678" , "id_cargo" : 2 , "id_dependencia" : 1 , "estado" : true }
Response { "success" : true , "message" : "Empleado creado exitosamente" , "data" : { "id_empleado" : 2 , "nombre" : "María" , "apellido" : "González" , "email" : "[email protected] " , "telefono" : "+57 301 234 5678" , "id_cargo" : 2 , "id_dependencia" : 1 , "estado" : true , "cargo" : { "id_cargo" : 2 , "nombre" : "Arquitecto" , "descripcion" : "Diseño y planificación arquitectónica" }, "dependencia" : { "id_dependencia" : 1 , "nombre" : "Proyectos" , "descripcion" : "Departamento de gestión de proyectos" }, "created_at" : "2024-01-20T14:30:00.000000Z" , "updated_at" : "2024-01-20T14:30:00.000000Z" } }
Validation Errors { "success" : false , "errors" : { "email" : [ "Este email electrónico ya está registrado" ], "password" : [ "La contraseña debe tener al menos 6 caracteres" ], "id_cargo" : [ "El cargo seleccionado no existe" ] } }
Get Employee This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
Retrieves a specific employee by ID with related cargo and dependencia information.
Path Parameters The employee’s unique identifier (id_empleado)
Response { "success" : true , "data" : { "id_empleado" : 1 , "nombre" : "Juan" , "apellido" : "Pérez" , "email" : "[email protected] " , "telefono" : "+57 300 123 4567" , "id_cargo" : 1 , "id_dependencia" : 1 , "estado" : true , "cargo" : { "id_cargo" : 1 , "nombre" : "Gerente de Proyectos" , "descripcion" : "Responsable de la gestión de proyectos" }, "dependencia" : { "id_dependencia" : 1 , "nombre" : "Proyectos" , "descripcion" : "Departamento de gestión de proyectos" }, "created_at" : "2024-01-15T10:30:00.000000Z" , "updated_at" : "2024-01-15T10:30:00.000000Z" } }
Error Response { "success" : false , "message" : "Empleado no encontrado" }
Update Employee This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
Updates an existing employee’s information. Note that the password is not updated through this endpoint.
Path Parameters The employee’s unique identifier (id_empleado)
Body Parameters Employee’s first name (max 120 characters)
Employee’s last name (max 120 characters)
Employee’s email address (max 150 characters, must be unique except for current record)
Employee’s phone number (max 30 characters)
Position ID that must exist in the cargo table
Department ID that must exist in the dependencia table
Request Example { "nombre" : "Juan Carlos" , "apellido" : "Pérez" , "email" : "[email protected] " , "telefono" : "+57 300 123 4567" , "id_cargo" : 1 , "id_dependencia" : 2 , "estado" : true }
Response { "success" : true , "message" : "Empleado actualizado exitosamente" , "data" : { "id_empleado" : 1 , "nombre" : "Juan Carlos" , "apellido" : "Pérez" , "email" : "[email protected] " , "telefono" : "+57 300 123 4567" , "id_cargo" : 1 , "id_dependencia" : 2 , "estado" : true , "cargo" : { "id_cargo" : 1 , "nombre" : "Gerente de Proyectos" }, "dependencia" : { "id_dependencia" : 2 , "nombre" : "Ventas" }, "updated_at" : "2024-01-21T09:15:00.000000Z" } }
Delete Employee This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
DELETE /api/empleados/{id}
Deletes an employee record from the system.
Path Parameters The employee’s unique identifier (id_empleado)
Response { "success" : true , "message" : "Empleado eliminado exitosamente" }
Error Response { "success" : false , "message" : "Empleado no encontrado" }
List Active Employees This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
GET /api/empleados/activos
Returns only employees with estado = true.
Response { "success" : true , "data" : [ { "id_empleado" : 1 , "nombre" : "Juan" , "apellido" : "Pérez" , "email" : "[email protected] " , "estado" : true , "cargo" : { ... }, "dependencia" : { ... } } ] }
List Inactive Employees This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
GET /api/empleados/inactivos
Returns only employees with estado = false.
Response { "success" : true , "data" : [ { "id_empleado" : 5 , "nombre" : "Pedro" , "apellido" : "López" , "email" : "[email protected] " , "estado" : false , "cargo" : { ... }, "dependencia" : { ... } } ] }
Toggle Employee Status This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
PATCH /api/empleados/{id}/cambiar-estado
Toggles an employee’s active status between true and false.
Path Parameters The employee’s unique identifier (id_empleado)
Response { "success" : true , "message" : "Estado del empleado actualizado exitosamente" , "data" : { "id_empleado" : 1 , "nombre" : "Juan" , "apellido" : "Pérez" , "estado" : false , "cargo" : { ... }, "dependencia" : { ... } } }
List Employees by Position This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
GET /api/empleados/cargo/{id_cargo}
Returns all employees assigned to a specific position/role.
Path Parameters Response { "success" : true , "data" : [ { "id_empleado" : 1 , "nombre" : "Juan" , "apellido" : "Pérez" , "id_cargo" : 1 , "cargo" : { "id_cargo" : 1 , "nombre" : "Gerente de Proyectos" }, "dependencia" : { ... } } ] }
List Employees by Department This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
GET /api/empleados/dependencia/{id_dependencia}
Returns all employees assigned to a specific department.
Path Parameters The department identifier
Response { "success" : true , "data" : [ { "id_empleado" : 1 , "nombre" : "Juan" , "apellido" : "Pérez" , "id_dependencia" : 1 , "cargo" : { ... }, "dependencia" : { "id_dependencia" : 1 , "nombre" : "Proyectos" } } ] }
Search Employees This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
POST /api/empleados/buscar
Searches employees by name, last name, or email using a case-insensitive pattern match.
Body Parameters Search term (minimum 2 characters)
Request Example Response { "success" : true , "data" : [ { "id_empleado" : 1 , "nombre" : "Juan" , "apellido" : "Pérez" , "email" : "[email protected] " , "cargo" : { ... }, "dependencia" : { ... } }, { "id_empleado" : 3 , "nombre" : "Juan Carlos" , "apellido" : "Rodríguez" , "email" : "[email protected] " , "cargo" : { ... }, "dependencia" : { ... } } ] }
Error Response { "success" : false , "message" : "No se encontraron empleados con ese término de búsqueda" }
Get Employee Statistics This endpoint is not explicitly defined in the routes file. You may need to add it to your API routes.
GET /api/empleados/estadisticas
Returns statistical information about employees including counts by position and department.
Response { "success" : true , "data" : { "total_empleados" : 25 , "empleados_activos" : 22 , "empleados_inactivos" : 3 , "por_cargo" : [ { "cargo" : "Gerente de Proyectos" , "total" : 3 }, { "cargo" : "Arquitecto" , "total" : 5 }, { "cargo" : "Ingeniero Civil" , "total" : 8 } ], "por_dependencia" : [ { "dependencia" : "Proyectos" , "total" : 12 }, { "dependencia" : "Ventas" , "total" : 8 }, { "dependencia" : "Administración" , "total" : 5 } ] } }
Authentication & Security Password Handling The Empleado model extends Laravel’s Authenticatable class and uses:
HasApiTokens : For Sanctum token-based authenticationNotifiable : For notification capabilitiesPassword Hashing : Passwords are automatically hashed using the 'hashed' cast
Hidden Fields The following fields are never returned in API responses:
Authentication Routes Password reset functionality is available through web routes:
POST /empleado/forgot-password - Request password reset linkPOST /empleado/reset-password - Reset password with token
Relationships Belongs To Cargo (Position)
Foreign Key: id_cargo
References: cargo.id_cargo
Always eager loaded in API responses
Dependencia (Department)
Foreign Key: id_dependencia
References: dependencia.id_dependencia
Always eager loaded in API responses
Validation Rules Create Employee Field Rules Error Messages nombre required, string, max:120 ”El nombre del empleado es obligatorio” apellido required, string, max:120 ”El apellido del empleado es obligatorio” email required, email, max:150, unique:empleado ”Este email electrónico ya está registrado” password required, string, min:6 ”La contraseña debe tener al menos 6 caracteres” telefono nullable, string, max:30 ”El teléfono no puede exceder 30 caracteres” id_cargo required, exists:cargo,id_cargo ”El cargo seleccionado no existe” id_dependencia required, exists:dependencia,id_dependencia ”La dependencia seleccionada no existe” estado boolean ”El estado debe ser verdadero o falso”
Update Employee Same rules as creation, except:
password is not included in updatesemail uniqueness excludes the current record
Database Schema Table : empleados Columns: - id_empleado ( primary key ) - nombre ( varchar 120 ) - apellido ( varchar 120 ) - email ( varchar 150 , unique ) - password ( hashed ) - telefono ( varchar 30 , nullable) - id_cargo ( foreign key -> cargo . id_cargo ) - id_dependencia ( foreign key -> dependencia . id_dependencia ) - estado ( boolean ) - created_at ( timestamp ) - updated_at ( timestamp ) - remember_token (nullable)
