GET /api/v2/incident/

Obtiene el listado paginado de incidencias con filtros avanzados y estadísticas globales.

Nota: Este endpoint es para administradores. Para el listado del empleado, usar GET_my.md.

Autenticación

• Header: Authorization: Bearer <token>
• Rol requerido: Admin

Query Parameters

Parámetro	Tipo	Requerido	Descripción
status	string	No	"open" | "closed" - Filtra por estado
limit	number	No	Límite de resultados (default: todos)
offset	number	No	Offset para paginación (default: 0)
schoolCourseId	number	No	Filtra por curso escolar
search	string	No	Búsqueda por ID de incidencia (si es número) o nombre/apellido de empleado
startDate	string	No	Fecha de inicio (ISO: 2026-01-01)
endDate	string	No	Fecha de fin (si no se especifica, hasta hoy)
incidentType	string	No	Tipo de incidencia (ver INCIDENT_TYPES.md)

Ejemplo

curl -X GET "$HOST/api/v2/incident/?status=open&limit=10&offset=0&search=Juan&startDate=2026-01-01" \
  -H "Authorization: Bearer $TOKEN"

Respuesta (200)

{
  "status": "success",
  "data": {
    "incidents": [
      {
        "id": 1,
        "description": "Fichaje fuera de horario",
        "status": "open",
        "reviewStatus": "underReview",
        "incidentType": "out_of_schedule",
        "timeRecordId": 456,
        "employeeId": 123,
        "schoolCourseId": 1,
        "createdAt": "2026-01-27T10:00:00.000Z",
        "updatedAt": "2026-01-27T10:00:00.000Z",
        "employee": {
          "id": 123,
          "name": "Juan",
          "lastName": "Pérez"
        }
      }
    ]
  },
  "counts": {
    "total": 50,
    "open": 15,
    "inReview": 8,
    "closed": 35
  },
  "pagination": {
    "totalItems": 15,
    "limit": 10,
    "offset": 0
  }
}

Campos de Respuesta

Campo	Descripción
data.incidents	Array de incidencias filtradas y paginadas
counts.total	Total de incidencias (sin filtros de estado)
counts.open	Incidencias con status = 'open'
counts.inReview	Incidencias abiertas en revisión
counts.closed	Incidencias cerradas
pagination.totalItems	Total de items que coinciden con el filtro actual

Notas

• Los contadores (counts) son globales, permitiendo mostrar las tabs (Todas, Abiertas, Cerradas) mientras se filtra.
• Si se proporciona schoolCourseId, los contadores también se filtran por ese curso.

Actualizaciones en Tiempo Real

Para recibir notificaciones cuando se crea una nueva incidencia o un empleado envía un mensaje, conectarse al socket y escuchar el evento incident_notification en la sala admins.

socket.on("incident_notification", (data) => {
  if (data.type === "new_incident") {
    // Actualizar lista de incidencias
  }
});

Ver documentación completa: Notificaciones Socket