Overview The Departments API (Dependencias) allows you to manage organizational departments within Core Projects. Departments organize employees into functional units and provide structure to your organization. This API supports CRUD operations, employee listings, and statistical reporting.
The Department Object Unique identifier for the department
Department name (max 80 characters, must be unique)
Department description (max 200 characters)
Array of employees assigned to this department Employee’s position details
Number of employees in the department (available when using withCount endpoint)
Timestamp when the department was created
Timestamp when the department was last updated
List All Departments Returns a list of all departments with their associated employees.
Response { "success" : true , "data" : [ { "id_dependencia" : 1 , "nombre" : "Proyectos" , "descripcion" : "Departamento de gestión de proyectos de construcción" , "empleados" : [ { "id_empleado" : 1 , "nombre" : "Juan" , "apellido" : "Pérez" , "email" : "[email protected] " , "estado" : true , "cargo" : { "id_cargo" : 1 , "nombre" : "Gerente de Proyectos" } } ], "created_at" : "2024-01-10T08:00:00.000000Z" , "updated_at" : "2024-01-10T08:00:00.000000Z" }, { "id_dependencia" : 2 , "nombre" : "Ventas" , "descripcion" : "Departamento comercial y de ventas" , "empleados" : [], "created_at" : "2024-01-10T08:00:00.000000Z" , "updated_at" : "2024-01-10T08:00:00.000000Z" } ] }
Create Department Creates a new department in the organization.
Body Parameters Department name (max 80 characters, must be unique)
Department description (max 200 characters)
Request Example { "nombre" : "Recursos Humanos" , "descripcion" : "Departamento de gestión de talento humano y nómina" }
Response { "success" : true , "message" : "Dependencia creada exitosamente" , "data" : { "id_dependencia" : 3 , "nombre" : "Recursos Humanos" , "descripcion" : "Departamento de gestión de talento humano y nómina" , "created_at" : "2024-01-20T10:30:00.000000Z" , "updated_at" : "2024-01-20T10:30:00.000000Z" } }
Validation Errors { "success" : false , "errors" : { "nombre" : [ "Esta dependencia ya existe en el sistema" ], "descripcion" : [ "La descripción no puede exceder 200 caracteres" ] } }
Get Department GET /api/dependencias/{id}
Retrieves a specific department by ID with all associated employees and their positions.
Path Parameters The department’s unique identifier (id_dependencia)
Response { "success" : true , "data" : { "id_dependencia" : 1 , "nombre" : "Proyectos" , "descripcion" : "Departamento de gestión de proyectos de construcción" , "empleados" : [ { "id_empleado" : 1 , "nombre" : "Juan" , "apellido" : "Pérez" , "email" : "[email protected] " , "telefono" : "+57 300 123 4567" , "estado" : true , "cargo" : { "id_cargo" : 1 , "nombre" : "Gerente de Proyectos" , "descripcion" : "Responsable de la gestión de proyectos" } }, { "id_empleado" : 2 , "nombre" : "María" , "apellido" : "González" , "email" : "[email protected] " , "telefono" : "+57 301 234 5678" , "estado" : true , "cargo" : { "id_cargo" : 2 , "nombre" : "Arquitecto" , "descripcion" : "Diseño y planificación arquitectónica" } } ], "created_at" : "2024-01-10T08:00:00.000000Z" , "updated_at" : "2024-01-10T08:00:00.000000Z" } }
Error Response { "success" : false , "message" : "Dependencia no encontrada" }
Update Department PUT /api/dependencias/{id}
Updates an existing department’s information.
Path Parameters The department’s unique identifier (id_dependencia)
Body Parameters Department name (max 80 characters, must be unique except for current record)
Department description (max 200 characters)
Request Example { "nombre" : "Proyectos y Construcción" , "descripcion" : "Departamento de gestión y ejecución de proyectos de construcción" }
Response { "success" : true , "message" : "Dependencia actualizada exitosamente" , "data" : { "id_dependencia" : 1 , "nombre" : "Proyectos y Construcción" , "descripcion" : "Departamento de gestión y ejecución de proyectos de construcción" , "created_at" : "2024-01-10T08:00:00.000000Z" , "updated_at" : "2024-01-21T09:15:00.000000Z" } }
Delete Department DELETE /api/dependencias/{id}
Deletes a department from the system. This operation will fail if the department has associated employees.
Path Parameters The department’s unique identifier (id_dependencia)
Response { "success" : true , "message" : "Dependencia eliminada exitosamente" }
Error Responses Department Not Found { "success" : false , "message" : "Dependencia no encontrada" }
Has Associated Employees { "success" : false , "message" : "No se puede eliminar la dependencia porque tiene empleados asociados" }
You cannot delete a department that has employees assigned to it. First reassign or remove the employees, then delete the department.
List Departments with Count GET /api/dependencias/with-count
Returns all departments with a count of employees in each department.
Response { "success" : true , "data" : [ { "id_dependencia" : 1 , "nombre" : "Proyectos" , "descripcion" : "Departamento de gestión de proyectos" , "empleados_count" : 12 , "created_at" : "2024-01-10T08:00:00.000000Z" , "updated_at" : "2024-01-10T08:00:00.000000Z" }, { "id_dependencia" : 2 , "nombre" : "Ventas" , "descripcion" : "Departamento comercial" , "empleados_count" : 8 , "created_at" : "2024-01-10T08:00:00.000000Z" , "updated_at" : "2024-01-10T08:00:00.000000Z" }, { "id_dependencia" : 3 , "nombre" : "Administración" , "descripcion" : "Departamento administrativo" , "empleados_count" : 5 , "created_at" : "2024-01-10T08:00:00.000000Z" , "updated_at" : "2024-01-10T08:00:00.000000Z" } ] }
This endpoint is useful for dashboard displays and reports showing department sizes.
Get Department Employees GET /api/dependencias/{id}/empleados
Returns all active employees assigned to a specific department with their position information.
Path Parameters The department’s unique identifier (id_dependencia)
Response { "success" : true , "data" : { "dependencia" : "Proyectos" , "descripcion" : "Departamento de gestión de proyectos de construcción" , "empleados" : [ { "id_empleado" : 1 , "nombre" : "Juan" , "apellido" : "Pérez" , "email" : "[email protected] " , "telefono" : "+57 300 123 4567" , "estado" : true , "cargo" : { "id_cargo" : 1 , "nombre" : "Gerente de Proyectos" , "descripcion" : "Responsable de la gestión de proyectos" } }, { "id_empleado" : 2 , "nombre" : "María" , "apellido" : "González" , "email" : "[email protected] " , "telefono" : "+57 301 234 5678" , "estado" : true , "cargo" : { "id_cargo" : 2 , "nombre" : "Arquitecto" , "descripcion" : "Diseño y planificación arquitectónica" } } ] } }
This endpoint only returns employees with estado = true (active employees).
Error Response { "success" : false , "message" : "Dependencia no encontrada" }
Get Department Statistics GET /api/dependencias/{id}/estadisticas
Returns detailed statistics about a department including active and inactive employee counts.
Path Parameters The department’s unique identifier (id_dependencia)
Response { "success" : true , "data" : { "id_dependencia" : 1 , "nombre" : "Proyectos" , "descripcion" : "Departamento de gestión de proyectos de construcción" , "total_empleados" : 12 , "empleados_activos" : 11 , "empleados_inactivos" : 1 } }
Error Response { "success" : false , "message" : "Dependencia no encontrada" }
This endpoint provides a quick overview of department health and staffing levels.
Relationships Has Many Empleados (Employees)
Foreign Key: empleados.id_dependencia
References: id_dependencia
A department can have many employees
Deletion is prevented if employees exist
Validation Rules Create Department Field Rules Error Messages nombre required, string, max:80, unique:dependencias ”Esta dependencia ya existe en el sistema” descripcion nullable, string, max:200 ”La descripción no puede exceder 200 caracteres”
Update Department Same rules as creation, except:
nombre uniqueness excludes the current record
Database Schema Table : dependencias Columns: - id_dependencia ( primary key ) - nombre ( varchar 80 , unique ) - descripcion ( varchar 200 , nullable) - created_at ( timestamp ) - updated_at ( timestamp ) Relationships: - Has many empleados (one - to - many)
Business Rules
Unique Names : Department names must be unique across the organizationDeletion Constraints : Departments with employees cannot be deletedEmployee Filtering : The empleados endpoint only returns active employeesCascade Prevention : No cascade delete - must manually reassign employees first
Common Use Cases Organizational Dashboard Use the with-count endpoint to display department sizes:
const response = await fetch ( '/api/dependencias/with-count' ); const { data } = await response . json (); // Display department cards with employee counts data . forEach ( dept => { console . log ( ` ${ dept . nombre } : ${ dept . empleados_count } employees` ); });
Department Reassignment Before deleting a department, reassign employees:
// 1. Get all employees in the department const deptResponse = await fetch ( '/api/dependencias/1/empleados' ); const { data : { empleados } } = await deptResponse . json (); // 2. Reassign each employee to a new department for ( const emp of empleados ) { await fetch ( `/api/empleados/ ${ emp . id_empleado } ` , { method: 'PUT' , body: JSON . stringify ({ ... emp , id_dependencia: 2 }) }); } // 3. Now delete the department await fetch ( '/api/dependencias/1' , { method: 'DELETE' });
Department Statistics Report const statsResponse = await fetch ( '/api/dependencias/1/estadisticas' ); const { data } = await statsResponse . json (); console . log ( `Department: ${ data . nombre } ` ); console . log ( `Active: ${ data . empleados_activos } ` ); console . log ( `Inactive: ${ data . empleados_inactivos } ` ); console . log ( `Total: ${ data . total_empleados } ` );
