Skip to main content

​
Overview

The Employee Management API provides endpoints to query employee information, retrieve catalogs with filters, and access supervisor lists. This guide covers the core employee query operations available in the Integra system.

​
Retrieving Employee Catalog

Get a filtered list of employees based on various criteria.
1

Prepare filter parameters

Endpoint: GET /empleadosAvailable Filter Parameters:
  • unidadId - Filter by unit/location
  • departamentoId - Filter by department
  • puestoId - Filter by position
  • supervisorId - Filter by supervisor
  • zonaId - Filter by zone
  • activos - Filter by active status (boolean)
  • codigo - Filter by employee code
  • nombre - Search by name
All parameters are optional and can be combined for precise filtering.
2

Execute the query

Example: Get all active employees in unit 5
curl -X GET "https://api.example.com/empleados?unidadId=5&activos=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
Example: Search employees by name
curl -X GET "https://api.example.com/empleados?nombre=Juan" \
  -H "Authorization: Bearer YOUR_TOKEN"
Example: Get employees by department and position
curl -X GET "https://api.example.com/empleados?departamentoId=10&puestoId=3" \
  -H "Authorization: Bearer YOUR_TOKEN"
3

Process the response

Success Response (200 OK):
{
  "data": [
    {
      "id": 123,
      "codigo": "EMP001",
      "nombre": "Juan",
      "apellidoPaterno": "García",
      "apellidoMaterno": "López",
      "nombreCompleto": "Juan García López",
      "puesto": {
        "id": 3,
        "nombre": "Supervisor"
      },
      "unidad": {
        "id": 5,
        "nombre": "Unidad Centro"
      },
      "fechaAlta": "2024-01-15",
      "fechaBaja": null,
      "fechaReingreso": null,
      "estatus": "ACTIVO",
      "departamento": {
        "id": 10,
        "nombre": "Operaciones"
      },
      "contacto": {
        "telefono": "555-1234",
        "email": "[email protected]"
      },
      "sexo": "M",
      "gestores": []
    }
  ],
  "message": "Empleado"
}
Employee Object Fields:
  • id - Unique employee identifier
  • codigo - Employee code/number
  • nombre - First name
  • apellidoPaterno - Paternal surname
  • apellidoMaterno - Maternal surname
  • nombreCompleto - Full name
  • puesto - Position/job title object
  • unidad - Unit/location assignment
  • fechaAlta - Hire date
  • fechaBaja - Termination date (null if active)
  • fechaReingreso - Rehire date (if applicable)
  • estatus - Employee status
  • departamento - Department assignment
  • contacto - Contact information
  • sexo - Gender
  • gestores - List of assigned managers/supervisors

​
Getting Supervisor List

Retrieve a list of employees with supervisor roles.
1

Query supervisors

Endpoint: GET /empleados/supervisoresQuery Parameters:
  • activos (optional) - Filter by active status (boolean)
Example: Get all active supervisors
curl -X GET "https://api.example.com/empleados/supervisores?activos=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
Example: Get all supervisors (active and inactive)
curl -X GET "https://api.example.com/empleados/supervisores" \
  -H "Authorization: Bearer YOUR_TOKEN"
2

Review supervisor data

Success Response (200 OK):
{
  "data": [
    {
      "id": 45,
      "codigo": "SUP001",
      "nombreCompleto": "María Rodríguez Pérez",
      "puesto": {
        "id": 2,
        "nombre": "Supervisor de Area"
      },
      "unidad": {
        "id": 5,
        "nombre": "Unidad Centro"
      },
      "estatus": "ACTIVO"
    },
    {
      "id": 67,
      "codigo": "SUP002",
      "nombreCompleto": "Carlos Hernández Silva",
      "puesto": {
        "id": 2,
        "nombre": "Supervisor de Area"
      },
      "unidad": {
        "id": 8,
        "nombre": "Unidad Norte"
      },
      "estatus": "ACTIVO"
    }
  ],
  "message": "Supervisores activos"
}

​
Getting Employee Details

Retrieve complete details for a specific employee by ID.
1

Request employee details

Endpoint: GET /empleados/{id}/detallesPath Parameters:
  • id - Employee ID (required)
curl -X GET "https://api.example.com/empleados/123/detalles" \
  -H "Authorization: Bearer YOUR_TOKEN"
2

Access detailed information

Success Response (200 OK):
{
  "data": {
    "id": 123,
    "codigo": "EMP001",
    "nombre": "Juan",
    "apellidoPaterno": "García",
    "apellidoMaterno": "López",
    "nombreCompleto": "Juan García López",
    "puesto": {
      "id": 3,
      "nombre": "Supervisor"
    },
    "unidad": {
      "id": 5,
      "nombre": "Unidad Centro",
      "direccion": "Av. Principal 123",
      "zona": {
        "id": 2,
        "nombre": "Zona Centro"
      }
    },
    "fechaAlta": "2024-01-15",
    "fechaBaja": null,
    "fechaReingreso": null,
    "estatus": "ACTIVO",
    "departamento": {
      "id": 10,
      "nombre": "Operaciones",
      "descripcion": "Departamento de Operaciones"
    },
    "contacto": {
      "telefono": "555-1234",
      "email": "[email protected]",
      "celular": "555-5678"
    },
    "sexo": "M",
    "gestores": [
      {
        "id": 45,
        "nombreCompleto": "María Rodríguez Pérez",
        "tipo": "SUPERVISOR"
      }
    ]
  },
  "message": "Detalles de empleado"
}
This endpoint returns complete employee information including:
  • Full personal information
  • Position and department details
  • Unit assignment with location
  • Contact information
  • Manager/supervisor assignments
  • Employment dates and status

​
Employee Status Values

Common employee status values in the system:
  • ACTIVO - Active employee
  • BAJA - Terminated employee
  • SUSPENDIDO - Suspended employee
  • LICENCIA - Employee on leave

​
Filtering Best Practices

​
Combining Filters

You can combine multiple filter parameters for precise queries: 
curl -X GET "https://api.example.com/empleados?unidadId=5&departamentoId=10&activos=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
This returns all active employees in unit 5 and department 10.

​
Performance Considerations

  • Use specific filters when possible to reduce response size
  • Filter by activos=true when you only need current employees
  • Combine unidadId and departamentoId for targeted queries
  • Use employee code for exact lookups

​
Common Use Cases

​
Get all active employees in a specific location

curl -X GET "https://api.example.com/empleados?unidadId=5&activos=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Find employees by supervisor

curl -X GET "https://api.example.com/empleados?supervisorId=45" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get employees in a specific department and position

curl -X GET "https://api.example.com/empleados?departamentoId=10&puestoId=3" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Search for a specific employee by code

curl -X GET "https://api.example.com/empleados?codigo=EMP001" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Reference

Controller: EmpleadoController.java at /empleado/controller/EmpleadoController.java:1 Related Models:
  • Empleado.java - Employee entity model
  • FiltroEmpleado - Employee filter parameters
  • Puesto - Position/job title
  • Unidad - Unit/location
  • Departamento - Department
  • Contacto - Contact information
  • Gestor - Manager/supervisor relationship

​
Next Steps

Attendance Recording

Record and manage employee attendance

Reports Generation

Generate reports based on employee data

Build docs developers (and LLMs) love

Get started for freeTalk to us