API Endpoints Not Yet Implemented : RESTful endpoints for report operations are not available in the current version. This page documents expected operations and data structures for reference. Report management is currently performed through the Eloquent ORM.
Expected Operations The following operations represent the intended API surface for future implementation:
List Reports Retrieve a list of failure reports.
Query Parameters Filter by status: abierto, asignado, en_progreso, resuelto, cerrado
Filter by priority: alta, media, baja
Filter reports for a specific asset
Filter reports created by a specific user
Filter reports created after this date
Filter reports created before this date
Include related data: activo, usuario, mantenimientos
Response { "data" : [ { "id" : 10 , "usuario_id" : 15 , "activo_id" : 5 , "descripcion" : "Servidor presenta sobrecalentamiento constante" , "prioridad" : "alta" , "estado" : "abierto" , "created_at" : "2026-03-05T14:30:00Z" , "updated_at" : "2026-03-05T14:30:00Z" } ], "meta" : { "total" : 1 , "por_estado" : { "abierto" : 1 , "asignado" : 0 , "en_progreso" : 0 , "resuelto" : 0 , "cerrado" : 0 }, "por_prioridad" : { "alta" : 1 , "media" : 0 , "baja" : 0 } } }
Authorization All authenticated users can list reports. Regular users see only their own reports. Supervisors and admins see all reports.
Get Single Report Retrieve detailed information about a specific report.
Path Parameters Query Parameters Include related data: activo, usuario, mantenimientos
Response { "data" : { "id" : 10 , "usuario_id" : 15 , "activo_id" : 5 , "descripcion" : "Servidor presenta sobrecalentamiento constante. Temperatura alcanza 85°C bajo carga normal." , "prioridad" : "alta" , "estado" : "en_progreso" , "created_at" : "2026-03-05T14:30:00Z" , "updated_at" : "2026-03-06T09:00:00Z" , "usuario" : { "id" : 15 , "name" : "Juan Pérez" , "email" : "[email protected] " }, "activo" : { "id" : 5 , "estado" : "mantenimiento" , "articulo" : { "tipo" : "equipo" , "marca" : "Dell" , "modelo" : "PowerEdge R740" }, "ubicacion" : { "edificio" : "Data Center" , "piso" : "1" , "salon" : "Server Room A" } }, "mantenimientos" : [ { "id" : 5 , "tipo" : "correctivo" , "estado" : "en_proceso" , "fecha_apertura" : "2026-03-06T08:00:00Z" , "supervisor_id" : 2 , "tecnico_principal_id" : 3 } ] } }
Create Report Submit a new failure report for an asset.
Request Body ID of the asset with the issue
Detailed description of the failure or issue. Be specific about symptoms, when the issue started, and any relevant context.
Priority level: alta, media, baja
Priority Selection Guide
When to use 'alta' (high priority)
Asset is completely non-functional
Safety hazard is present
Critical business operations are impacted
Multiple users are affected
Issue is worsening rapidly
When to use 'media' (medium priority)
When to use 'baja' (low priority)
Minor cosmetic issues
Asset fully functional despite issue
Workarounds are available
Can be addressed during scheduled maintenance
Example Request curl -X POST "https://api.gima.example/api/reportes" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "activo_id": 5, "descripcion": "Servidor presenta sobrecalentamiento constante. Temperatura alcanza 85°C bajo carga normal de trabajo. Ventiladores funcionan a máxima velocidad. Inicio de síntomas hace 3 días.", "prioridad": "alta" }'
Example Response { "data" : { "id" : 10 , "usuario_id" : 15 , "activo_id" : 5 , "descripcion" : "Servidor presenta sobrecalentamiento constante. Temperatura alcanza 85°C bajo carga normal de trabajo. Ventiladores funcionan a máxima velocidad. Inicio de síntomas hace 3 días." , "prioridad" : "alta" , "estado" : "abierto" , "created_at" : "2026-03-06T14:30:00Z" , "updated_at" : "2026-03-06T14:30:00Z" }, "message" : "Report created successfully" }
Authorization All authenticated users can create reports.
When creating a high-priority report, consider notifying supervisors immediately via email or push notification
Update Report Update an existing report’s information.
PUT /api/reportes/{id} PATCH /api/reportes/{id}
Path Parameters Request Body Update the issue description
Change priority: alta, media, baja
Update status: abierto, asignado, en_progreso, resuelto, cerrado
Example Request curl -X PATCH "https://api.gima.example/api/reportes/10" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "estado": "asignado" }'
Authorization Requires supervisor or admin role
Regular users cannot update reports after creation. Contact a supervisor for changes.
Assign Report Assign a report to a supervisor or technician.
POST /api/reportes/{id}/asignar
Path Parameters Request Body ID of the supervisor to assign
ID of the lead technician (if known)
Example Request curl -X POST "https://api.gima.example/api/reportes/10/asignar" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "supervisor_id": 2, "tecnico_id": 3 }'
Response { "data" : { "id" : 10 , "estado" : "asignado" , "updated_at" : "2026-03-06T15:00:00Z" }, "message" : "Report assigned successfully" }
Authorization Requires supervisor or admin role
Close Report Mark a report as closed after verification.
POST /api/reportes/{id}/cerrar
Path Parameters Request Body Notes about the resolution verification
Example Request curl -X POST "https://api.gima.example/api/reportes/10/cerrar" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "notas_cierre": "Verificado funcionamiento correcto. Temperatura estable en 45°C." }'
Response { "data" : { "id" : 10 , "estado" : "cerrado" , "updated_at" : "2026-03-07T16:00:00Z" }, "message" : "Report closed successfully" }
Authorization Requires supervisor, admin, or must be the original report creator
Reports can only be closed if associated maintenance is completed and validated
Delete Report Remove a report from the system.
DELETE /api/reportes/{id}
Path Parameters Response { "message" : "Report deleted successfully" }
Authorization Requires admin role only
Reports with associated maintenance cannot be deleted. Consider closing instead.
Report Statistics Get aggregated statistics about reports.
GET /api/reportes/estadisticas
Query Parameters Start date for statistics
Statistics for specific asset
Response { "data" : { "total_reportes" : 245 , "por_estado" : { "abierto" : 12 , "asignado" : 8 , "en_progreso" : 15 , "resuelto" : 5 , "cerrado" : 205 }, "por_prioridad" : { "alta" : 35 , "media" : 150 , "baja" : 60 }, "tiempo_promedio_resolucion" : { "alta" : "18.5 hours" , "media" : "52.3 hours" , "baja" : "168.5 hours" }, "activos_con_mas_reportes" : [ { "activo_id" : 5 , "total_reportes" : 15 , "articulo" : { "marca" : "Dell" , "modelo" : "PowerEdge R740" } } ], "mttr_general" : "45.2 hours" , "mtta_general" : "4.3 hours" } }
Authorization Requires reporter, supervisor, or admin role
Report Monthly Summary Generate monthly report for download.
GET /api/reportes/mensuales
This endpoint is referenced in routes/api.php:49-51 under the reporter role
Query Parameters Output format: json, excel, pdf
Example Request curl -X GET "https://api.gima.example/api/reportes/mensuales?mes=3&anio=2026&formato=excel" \ -H "Authorization: Bearer {token}" \ --output reportes_marzo_2026.xlsx
Authorization Requires reporter or admin role
Best Practices Writing Good Report Descriptions
Describe Symptoms
What exactly is happening? Be specific about observable behavior.
Provide Context
When did it start? Has it happened before? What changed recently?
Include Impact
How does this affect work? How many people are impacted?
Add Details
Include error messages, measurements, or any relevant data.
Good Example { "descripcion" : "Servidor web presenta lentitud extrema desde el 5/03/2026 a las 14:00. Tiempo de respuesta aumentó de 200ms a 5000ms. Afecta a todos los usuarios del sistema. Logs muestran error 'connection pool exhausted'. CPU al 95% constante." }
Bad Example { "descripcion" : "No funciona bien" }
Setting Priority When in doubt, start with media priority. Supervisors can escalate if needed.
Don’t abuse alta priority. It should be reserved for genuine emergencies that require immediate response.
Common Error Responses Validation Error (422) { "message" : "The given data was invalid." , "errors" : { "activo_id" : [ "The activo id field is required." ], "descripcion" : [ "The descripcion field is required." ] } }
Asset Not Found (404) { "message" : "Asset not found" }
Unauthorized (401) { "message" : "Unauthenticated." }
Forbidden (403) { "message" : "You do not have permission to update this report" }
