Incidents API

The Incidents API manages production incidents reported during shifts. Incidents track quality issues, equipment failures, safety events, and other deviations from normal operations.

Authentication

All write endpoints require MANAGE_PRODUCTION permission. Read endpoints require authentication.

Get All Incidents

GET /api/incidentes

Returns all production incidents, ordered by creation date descending.

Response

Array of incident objects.

integer

Incident ID

titulo

string

Incident title/summary

descripcion

string

Detailed incident description

severidad

string

Severity level: Baja, Media, Alta

estado

string

Incident state: Abierto, En investigación, Cerrado

proceso_id

integer

Affected process ID (1-9)

proceso_nombre

string

Affected process name

turno

string

Shift when incident occurred: T1, T2, T3

fecha_incidente

string

ISO timestamp of incident occurrence

reportado_por

string

Username of person who reported the incident

accion_correctiva

string

Corrective action taken (null until closed)

fecha_cierre

string

ISO timestamp of incident closure (null if open)

Example Request

cURL

curl -X GET https://api.example.com/api/incidentes \
  -H "Authorization: Bearer <token>"

JavaScript

const response = await fetch('/api/incidentes', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});
const incidentes = await response.json();

Example Response

{
  "success": true,
  "data": [
    {
      "id": 42,
      "titulo": "Contaminación en lote EXT-001-12",
      "descripcion": "Se detectó material extranjero en el lote durante inspección de calidad. Aproximadamente 50kg afectados.",
      "severidad": "Alta",
      "estado": "En investigación",
      "proceso_id": 1,
      "proceso_nombre": "Extrusor PP",
      "turno": "T1",
      "fecha_incidente": "2026-03-06T10:30:00Z",
      "reportado_por": "Juan Pérez",
      "accion_correctiva": null,
      "fecha_cierre": null
    },
    {
      "id": 41,
      "titulo": "Falla mecánica TEL-03",
      "descripcion": "Telar 3 presentó falla en tensor principal. Producción detenida por 2 horas.",
      "severidad": "Media",
      "estado": "Cerrado",
      "proceso_id": 2,
      "proceso_nombre": "Telares",
      "turno": "T2",
      "fecha_incidente": "2026-03-05T17:15:00Z",
      "reportado_por": "María López",
      "accion_correctiva": "Reemplazo de tensor. Mantenimiento preventivo programado.",
      "fecha_cierre": "2026-03-05T20:00:00Z"
    }
  ]
}

Create Incident

POST /api/incidentes

Permission: MANAGE_PRODUCTION Reports a new production incident.

Request Body

titulo

string

required

Brief incident title/summary (max 200 characters)

descripcion

string

required

Detailed description of what happened, impact, and context

severidad

string

required

Severity level:

Baja - Minor issue, no production impact
Media - Moderate impact, requires attention
Alta - Critical issue, immediate action required

proceso_id

integer

required

ID of affected process (1-9)

turno

string

required

Shift when incident occurred: T1, T2, or T3

fecha_incidente

string

ISO timestamp of incident occurrence (defaults to current time if not provided)

reportado_por

string

Username of reporter (defaults to authenticated user if not provided)

Example Request

cURL

curl -X POST https://api.example.com/api/incidentes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "Desviación de temperatura en extrusor",
    "descripcion": "Zona 5 del extrusor alcanzó 280°C, excediendo el setpoint de 260°C por 15 minutos. Se ajustó controlador y se validó calidad del producto.",
    "severidad": "Media",
    "proceso_id": 1,
    "turno": "T2"
  }'

JavaScript

const response = await fetch('/api/incidentes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    titulo: 'Desviación de temperatura en extrusor',
    descripcion: 'Zona 5 del extrusor alcanzó 280°C...',
    severidad: 'Media',
    proceso_id: 1,
    turno: 'T2'
  })
});
const incidente = await response.json();

Example Response

{
  "success": true,
  "data": {
    "id": 43,
    "titulo": "Desviación de temperatura en extrusor",
    "estado": "Abierto",
    "fecha_incidente": "2026-03-06T15:45:00Z",
    "reportado_por": "Carlos Ruiz"
  }
}

Update Incident

PUT /api/incidentes/:id

Permission: MANAGE_PRODUCTION Updates an existing incident, typically to add investigation details or close with corrective action.

Path Parameters

integer

required

Incident ID

Request Body

All fields are optional. Only provided fields will be updated.

estado

string

Update state: Abierto, En investigación, Cerrado

accion_correctiva

string

Corrective action taken (required when closing incident)

descripcion

string

Update description with additional findings

severidad

string

Update severity if initial assessment was incorrect

Business Rules

When changing state to Cerrado, accion_correctiva is mandatory
Closing an incident automatically sets fecha_cierre to current timestamp
Cannot reopen a closed incident (must create new incident if issue recurs)

Example Request - Close Incident

cURL

curl -X PUT https://api.example.com/api/incidentes/43 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "estado": "Cerrado",
    "accion_correctiva": "Se recalibró el controlador de temperatura y se verificó el correcto funcionamiento durante 4 horas de operación. Producto generado durante el incidente fue sometido a pruebas adicionales y cumple especificaciones."
  }'

Example Response

{
  "success": true,
  "data": {
    "id": 43,
    "estado": "Cerrado",
    "accion_correctiva": "Se recalibró el controlador de temperatura...",
    "fecha_cierre": "2026-03-06T16:30:00Z"
  }
}

Incident State Machine

State Transitions:

Abierto → En investigación: When investigation starts
En investigación → Cerrado: When root cause identified and corrective action completed
Abierto → Cerrado: For minor incidents requiring immediate action

Severity Guidelines

Alta (High)

Safety incidents or near-misses
Product contamination or quality defects shipped to customers
Equipment failure causing complete production stoppage
Environmental incidents
Requires immediate management notification

Media (Medium)

Equipment malfunctions causing delays but not complete stoppage
Quality deviations detected before shipment
Process parameter excursions
Requires investigation within 24 hours

Baja (Low)

Minor operational issues
Cosmetic defects
Brief delays or interruptions
Can be addressed during normal operations

Integration with Shift Logs

Incidents are integrated with the Bitácora (shift log) system:

Inline Reporting: For Extrusor PP, incidents can be recorded directly within process data using the incidentes array:

{
  "bitacora_id": 43,
  "proceso_id": 1,
  "incidentes": [
    {
      "hora": "10:30",
      "descripcion": "Temperatura Zona 5 fuera de rango",
      "accion": "Ajuste de controlador PID"
    }
  ]
}

Closure Validation: Shifts with open high-severity incidents may require supervisor approval before closure.
Traceability: Incidents are linked to specific shifts, processes, and production batches for full traceability.

Best Practices

Timely Reporting: Report incidents as soon as they occur. Delays in reporting can compromise investigation and corrective action.

Detailed Descriptions: Include:

What happened (observable facts)
When it happened (precise time if possible)
Where it happened (specific equipment/location)
Immediate actions taken
Material/production affected

Root Cause, Not Blame: Focus on identifying systemic issues and process improvements, not assigning blame to individuals.

Common Workflows

Equipment Failure

Report Incident

Operator reports equipment failure with severidad: Alta

Investigate

Maintenance team investigates, updates incident to En investigación

Corrective Action

Equipment repaired, maintenance log updated

Supervisor closes incident with detailed corrective action description

Follow-up

Preventive maintenance schedule adjusted based on failure analysis

Quality Deviation

Detection

Quality inspector detects deviation during sampling

Report

Inspector creates incident with affected batch information

Containment

Affected material quarantined, batch marked in system

Investigation

Production and quality teams investigate root cause

Resolution

Process adjusted, affected material dispositioned, incident closed

Error Responses

400 Bad Request

Missing required fields or invalid data:

{
  "success": false,
  "error": "El campo 'titulo' es requerido."
}

404 Not Found

Incident ID not found:

{
  "success": false,
  "error": "Incidente no encontrado."
}

403 Forbidden

Insufficient permissions:

{
  "success": false,
  "error": "Permisos insuficientes."
}

Bitácora API - Shift log management
Quality API - Quality sample tracking
Audit Logs - Incident audit trail

Authentication

Production

Quality Control

Resources

Personnel & Groups

Dashboard & Analytics

Operations

System

Incidents API

Incidents API

Authentication

Get All Incidents

Response

Example Request

Example Response

Create Incident

Request Body

Example Request

Example Response

Update Incident

Path Parameters

Request Body

Business Rules

Example Request - Close Incident

Example Response

Incident State Machine

Severity Guidelines

Alta (High)

Media (Medium)

Baja (Low)

Integration with Shift Logs

Best Practices

Common Workflows

Equipment Failure

Quality Deviation

Error Responses

Build docs developers (and LLMs) love

Authentication

Production

Quality Control

Resources

Personnel & Groups

Dashboard & Analytics

Operations

System

​Incidents API

​Authentication

​Get All Incidents

​Response

​Example Request

​Example Response

​Create Incident

​Request Body

​Example Request

​Example Response

​Update Incident

​Path Parameters

​Request Body

​Business Rules

​Example Request - Close Incident

​Example Response

​Incident State Machine

​Severity Guidelines

​Alta (High)

​Media (Medium)

​Baja (Low)

​Integration with Shift Logs

​Best Practices

​Common Workflows

​Equipment Failure

​Quality Deviation

​Error Responses

​Related Endpoints

Build docs developers (and LLMs) love

Incidents API

Authentication

Get All Incidents

Response

Example Request

Example Response

Create Incident

Request Body

Example Request

Example Response

Update Incident

Path Parameters

Request Body

Business Rules

Example Request - Close Incident

Example Response

Incident State Machine

Severity Guidelines

Alta (High)

Media (Medium)

Baja (Low)

Integration with Shift Logs

Best Practices

Common Workflows

Equipment Failure

Quality Deviation

Error Responses

Related Endpoints