Reports API Overview

Introduction

This page documents the failure reports (reportes) data model in GIMA. Reports are created when users identify issues with assets that require attention. These reports trigger corrective maintenance workflows.

API Endpoints Not Yet Implemented: RESTful endpoints for reports are not available in the current version. This page documents the data model for reference. Report management is performed through the Eloquent ORM and application layer.

Report Model

Failure reports capture asset issues and drive the maintenance workflow. Each report:

Is created by a usuario (user) who identified the issue
References the affected activo (asset)
Contains a descripcion (description) of the problem
Has a prioridad (priority) level indicating urgency
Tracks estado (status) through its lifecycle
Can spawn mantenimientos (maintenance records) to address the issue

Report Fields

integer

Unique report identifier

usuario_id

integer

required

ID of the user who created the report

activo_id

integer

required

ID of the affected asset

descripcion

string

required

Description of the failure or issue

prioridad

string

required

Priority level: alta, media, baja

estado

string

required

Current status: abierto, asignado, en_progreso, resuelto, cerrado

created_at

datetime

Report creation timestamp

updated_at

datetime

Last update timestamp

Priority Levels

alta

string

High priority - immediate attention required. Asset is non-functional or poses safety risk.

media

string

Medium priority - attention needed soon. Asset functionality is degraded but operational.

baja

string

Low priority - can be addressed during scheduled maintenance. Minor issues.

Report States

abierto

string

Report has been created but not yet reviewed

asignado

string

Report has been assigned to a supervisor/technician

en_progreso

string

Active maintenance is underway to address the issue

resuelto

string

Issue has been fixed, awaiting verification

cerrado

string

Report is closed and verified as resolved

Report Workflow

Workflow Steps

Report Creation

Any authenticated user identifies an asset issue and creates a report with estado=“abierto”

Assignment

Supervisor reviews the report and assigns it to a technician (estado=“asignado”)

Maintenance Creation

System creates corrective maintenance record linked to the report

In Progress

Maintenance begins and report estado changes to “en_progreso”

Resolution

Maintenance is completed and report estado becomes “resuelto”

Verification

Supervisor or original reporter verifies the fix works

Closure

Report estado is set to “cerrado” and the workflow completes

Authentication & Authorization

Reports endpoints require authentication:

Authorization: Bearer {token}

Role Requirements

Create reports: All authenticated users
View reports: All authenticated users (own reports), supervisor and admin (all reports)
Update reports: supervisor, admin
Assign reports: supervisor, admin
Close reports: supervisor, admin, or original creator
Delete reports: admin only

Regular users can create reports for any asset but can only view their own reports

Complete Report Example

{
  "id": 10,
  "usuario_id": 15,
  "activo_id": 5,
  "descripcion": "Servidor presenta sobrecalentamiento constante. Temperatura alcanza 85°C bajo carga normal.",
  "prioridad": "alta",
  "estado": "resuelto",
  "created_at": "2026-03-05T14:30:00Z",
  "updated_at": "2026-03-07T16:00:00Z",
  "usuario": {
    "id": 15,
    "name": "Juan Pérez",
    "email": "[email protected]"
  },
  "activo": {
    "id": 5,
    "estado": "operativo",
    "articulo": {
      "tipo": "equipo",
      "marca": "Dell",
      "modelo": "PowerEdge R740",
      "descripcion": "Servidor de aplicaciones"
    },
    "ubicacion": {
      "edificio": "Data Center",
      "piso": "1",
      "salon": "Server Room A"
    }
  },
  "mantenimientos": [
    {
      "id": 5,
      "tipo": "correctivo",
      "estado": "completado",
      "fecha_apertura": "2026-03-06T08:00:00Z",
      "fecha_cierre": "2026-03-07T17:00:00Z",
      "descripcion": "Reparación de sistema de enfriamiento",
      "validado": true,
      "costo_total": 2500.00,
      "supervisor": {
        "id": 2,
        "name": "Carlos Supervisor"
      },
      "tecnico_principal": {
        "id": 3,
        "name": "Ana Técnico"
      }
    }
  ]
}

Key Concepts

Report to Maintenance Link

Reports and maintenance are tightly integrated:

A report can have multiple maintenance records addressing the same issue
Each corrective maintenance must reference a report via reporte_id
When maintenance is completed, the report status updates automatically
Reports track the full history of attempts to resolve the issue

Priority and Response Times

Priority levels guide response expectations:

Prioridad	Expected Response	Expected Resolution
alta	< 2 hours	< 24 hours
media	< 8 hours	< 3 days
baja	< 24 hours	Next scheduled maintenance

Asset State Management

When a high-priority report is created, consider automatically updating the asset’s estado to “fuera_servicio” until resolved

Common Patterns

Creating a High-Priority Report

{
  "activo_id": 5,
  "descripcion": "Servidor presenta sobrecalentamiento constante",
  "prioridad": "alta"
}

Filtering Reports by Status

GET /api/reportes?estado=abierto&prioridad=alta

GET /api/reportes/{id}?include=activo,usuario,mantenimientos

Base URL

Report endpoints can be accessed through different zones:

# Create and view own reports (all users)
/api/reportes/

# View and manage all reports (reporters, supervisors, admins)
/api/reportes/

Metrics and Analytics

The reporter role has special access to generate reports and analytics

Key metrics tracked:

Mean Time to Acknowledge (MTTA): Time from report creation to assignment
Mean Time to Repair (MTTR): Time from report creation to resolution
Reports by Priority: Distribution of alta/media/baja reports
Reports by Asset: Which assets have the most failures
Resolution Rate: Percentage of reports resolved within SLA

Authentication

Dashboards

Data Models

Reports API Overview

Introduction

Report Model

Report Fields

Priority Levels

Report States

Report Workflow

Workflow Steps

Authentication & Authorization

Role Requirements

Complete Report Example

Key Concepts

Report to Maintenance Link

Priority and Response Times

Asset State Management

Common Patterns

Creating a High-Priority Report

Filtering Reports by Status

Base URL

Metrics and Analytics

Create Reports

Maintenance API

Assets API

Build docs developers (and LLMs) love

Authentication

Dashboards

Data Models

​Introduction

​Report Model

​Report Fields

​Priority Levels

​Report States

​Report Workflow

​Workflow Steps

​Authentication & Authorization

​Role Requirements

​Complete Report Example

​Key Concepts

​Report to Maintenance Link

​Priority and Response Times

​Asset State Management

​Common Patterns

​Creating a High-Priority Report

​Filtering Reports by Status

​Including Related Data

​Base URL

​Metrics and Analytics

​Related Resources

Create Reports

Maintenance API

Assets API

Build docs developers (and LLMs) love

Introduction

Report Model

Report Fields

Priority Levels

Report States

Report Workflow

Workflow Steps

Authentication & Authorization

Role Requirements

Complete Report Example

Key Concepts

Report to Maintenance Link

Priority and Response Times

Asset State Management

Common Patterns

Creating a High-Priority Report

Filtering Reports by Status

Including Related Data

Base URL

Metrics and Analytics

Related Resources