Skip to main content

​
Paros (Downtime) API

The Paros API manages machine downtime events during production shifts, tracking causes, duration, and impact on production efficiency.

​
Authentication

  • Read operations: VIEW_PRODUCTION permission
  • Write operations: MANAGE_PRODUCTION permission

​
Get Downtime by Process

GET /api/paros?bitacora_id={id}&proceso_id={pid}
Permission: VIEW_PRODUCTION Returns all downtime events for a specific process in a shift.

​
Query Parameters

​
bitacora_id
integer
required
Bit\u00e1cora (shift log) ID
​
proceso_id
integer
required
Process ID (1-9)

​
Response

​
paros
array
Array of downtime events

​
Example Request

cURL
curl -X GET "https://api.example.com/api/paros?bitacora_id=43&proceso_id=2" \\
  -H "Authorization: Bearer <token>"

​
Example Response

{
  "success": true,
  "data": {
    "paros": [
      {
        "id": 101,
        "bitacora_id": 43,
        "proceso_id": 2,
        "maquina_id": 3,
        "tipo_paro_id": 2,
        "tipo_paro_nombre": "Mec\u00e1nico",
        "minutos": 45,
        "descripcion": "Falla en tensor principal - requiri\u00f3 ajuste y verificaci\u00f3n",
        "hora_inicio": "10:15",
        "hora_fin": "11:00",
        "registrado_por": "Juan P\u00e9rez"
      },
      {
        "id": 102,
        "bitacora_id": 43,
        "proceso_id": 2,
        "maquina_id": 5,
        "tipo_paro_id": 4,
        "tipo_paro_nombre": "Falta de material",
        "minutos": 20,
        "descripcion": "Espera de lote extrusor - lote anterior agotado",
        "hora_inicio": "13:00",
        "hora_fin": "13:20",
        "registrado_por": "Mar\u00eda L\u00f3pez"
      }
    ]
  }
}

​
Create Downtime Event

POST /api/paros
Permission: MANAGE_PRODUCTION Records a new downtime event.

​
Request Body

​
bitacora_id
integer
required
Bit\u00e1cora (shift log) ID
​
proceso_id
integer
required
Process ID
​
maquina_id
integer
Affected machine ID (optional for process-level downtime)
​
tipo_paro_id
integer
required
Downtime type ID (from motivos catalog)
​
minutos
integer
required
Duration in minutes (must be positive)
​
descripcion
string
required
Detailed description of the downtime cause (minimum 10 characters)
​
hora_inicio
string
required
Start time in HH:MM format (e.g., “10:15”)
​
hora_fin
string
required
End time in HH:MM format (e.g., “11:00”)

​
Business Rules

  • Total downtime for a shift cannot exceed programmed time (typically 480 minutes for 8-hour shift)
  • hora_fin must be after hora_inicio
  • Calculated duration (hora_fin - hora_inicio) must match minutos field
  • Downtime events are validated during shift closure

​
Example Request

cURL
curl -X POST https://api.example.com/api/paros \\
  -H "Authorization: Bearer <token>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "bitacora_id": 43,
    "proceso_id": 2,
    "maquina_id": 3,
    "tipo_paro_id": 1,
    "minutos": 30,
    "descripcion": "Falla el\u00e9ctrica en motor principal - requiri\u00f3 reseteo y verificaci\u00f3n",
    "hora_inicio": "14:00",
    "hora_fin": "14:30"
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": 103,
    "mensaje": "Paro registrado correctamente"
  }
}

​
Update Downtime Event

PUT /api/paros/:id
Permission: MANAGE_PRODUCTION Updates an existing downtime event.

​
Path Parameters

​
id
integer
required
Downtime event ID

​
Request Body

Same fields as create, all optional. Only provided fields will be updated.
Cannot update downtime events after shift is closed.

​
Delete Downtime Event

DELETE /api/paros/:id
Permission: MANAGE_PRODUCTION Deletes a downtime event.

​
Path Parameters

​
id
integer
required
Downtime event ID

​
Business Rules

  • Can only delete events from open shifts (estado = ABIERTA)
  • Deletion is logged in audit trail
  • Consider updating instead of deleting for audit purposes

​
Example Response

{
  "success": true,
  "data": {
    "mensaje": "Paro eliminado correctamente"
  }
}

​
Get Downtime Types

GET /api/paros/motivos
Permission: VIEW_PRODUCTION Returns the catalog of downtime types/categories.

​
Response

​
motivos
array
Array of downtime type objects

​
Example Response

{
  "success": true,
  "data": {
    "motivos": [
      {"id": 1, "nombre": "Falla el\u00e9ctrica", "categoria": "El\u00e9ctrico"},
      {"id": 2, "nombre": "Falla mec\u00e1nica", "categoria": "Mec\u00e1nico"},
      {"id": 3, "nombre": "Cambio de orden", "categoria": "Operacional"},
      {"id": 4, "nombre": "Falta de material", "categoria": "Externo"},
      {"id": 5, "nombre": "Rechazo de calidad", "categoria": "Calidad"},
      {"id": 6, "nombre": "Falta de personal", "categoria": "Externo"},
      {"id": 7, "nombre": "Limpieza/sanitizaci\u00f3n", "categoria": "Operacional"},
      {"id": 8, "nombre": "Corte de energ\u00eda", "categoria": "Externo"}
    ]
  }
}

​
Downtime Analysis

​
OEE Calculation

Downtime data feeds into Overall Equipment Effectiveness (OEE) calculations: 
Tiempo Disponible = Tiempo Programado - Paros Externos
Tiempo Operativo = Tiempo Disponible - Paros Internos
Disponibilidad = Tiempo Operativo / Tiempo Disponible

​
Categorization

Paros Externos (not counted against machine efficiency):
  • Falta de material
  • Falta de personal
  • Corte de energ\u00eda
  • Sin \u00f3rdenes programadas
Paros Internos (counted against machine efficiency):
  • Fallas mec\u00e1nicas
  • Fallas el\u00e9ctricas
  • Cambios de orden
  • Rechazos de calidad
  • Limpieza operacional

​
Integration with Shift Closure

From bitacora.service.js:45: 
async calcularResumenTiempo(bitacoraId, procesoId) {
  const status = await this.bitacoraRepository.getProcesoStatus(bitacoraId, procesoId);
  const tiempoProgramado = status ? status.tiempo_programado_minutos : 480;
  const totalParos = await this.paroRepository.sumMinutosByBitacoraAndProceso(bitacoraId, procesoId);
  const tiempoEfectivo = tiempoProgramado - totalParos;

  return {
    tiempo_programado: tiempoProgramado,
    total_paros: totalParos,
    tiempo_efectivo: tiempoEfectivo
  };
}
Closure Validation (bitacora.service.js:117):
  • Total downtime cannot exceed programmed time
  • Negative effective time blocks shift closure
  • All downtime must have valid motivo and description

​
Best Practices

Real-Time Recording: Record downtime events as they occur, not at end of shift. This ensures:
  • Accurate time tracking
  • Better root cause analysis
  • Timely response to recurring issues
Detailed Descriptions: Include specific information:
  • Component/system affected
  • Symptoms observed
  • Corrective actions taken
  • Follow-up required
Time Validation: Ensure hora_inicio and hora_fin match actual events. Inaccurate times distort efficiency metrics and prevent effective analysis.

​
Error Responses

​
400 Bad Request
Validation errors:
{
  "success": false,
  "error": "El tiempo efectivo no puede ser negativo. Total de paros (520 min) excede el tiempo programado (480 min)."
}
​
404 Not Found
Event not found:
{
  "success": false,
  "error": "Paro no encontrado."
}

Build docs developers (and LLMs) love

Get started for freeTalk to us