Bitácora (Shift Log) API

The Bitácora API manages shift-based production logging. Each shift (turno) has a dedicated bitácora that tracks production, quality, incidents, and operational data across all production processes.

Authentication

All endpoints require authentication via JWT token (header or cookie). Some endpoints require specific permissions:

MANAGE_QUALITY - Required for opening/closing shift logs
MANAGE_PRODUCTION - Required for saving process data

Core Concepts

Shift Structure:

T1 (Turno 1): 07:00 - 15:00
T2 (Turno 2): 15:00 - 23:00
T3 (Turno 3): 23:00 - 07:00 (next day)

Bitácora States:

ABIERTA - Active shift, data entry allowed
REVISION - Closed with deviations requiring review
CERRADA - Finalized, immutable

Get Current State

GET /api/bitacora/estado

Returns the current shift state with process summary and available actions.

Response Fields

abierta

boolean

Whether there is an active shift log.

bitacora

object

Current bitácora details.

Show bitacora properties

integer

Bitácora ID

turno

string

Shift: T1, T2, or T3

fecha_operativa

string

Operational date (YYYY-MM-DD)

inspector

string

Shift supervisor name

estado

string

ABIERTA, REVISION, or CERRADA

procesos

array

Summary of all production processes.

Show proceso properties

integer

Process ID (1-9)

nombre

string

Process name (e.g., “Extrusor PP”, “Telares”)

estadoProceso

string

Current state: SIN_DATOS, ESPERANDO_CALIDAD, COMPLETO, REVISION, etc.

produccionTotal

number

Total production quantity for this shift

unidad

string

Production unit (kg, m, unidades, impresiones, etc.)

calidadValidada

boolean

Whether quality samples have been validated

estadoTurno

string

Overall shift state: SIN_TURNO, EN_PROCESO, LISTO_PARA_CIERRE, CERRADO

siguienteAccion

string

Recommended next action: ABRIR_TURNO, IR_A_PROCESO, CERRAR_TURNO, etc.

puedeCerrarTurno

boolean

Whether all processes are complete and shift can be closed.

Example Request

cURL

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

JavaScript

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

Example Response

{
  "success": true,
  "data": {
    "abierta": true,
    "bitacora": {
      "id": 42,
      "turno": "T1",
      "fecha_operativa": "2026-03-06",
      "inspector": "Juan Pérez",
      "estado": "ABIERTA"
    },
    "procesos": [
      {
        "id": 1,
        "nombre": "Extrusor PP",
        "estadoProceso": "COMPLETO",
        "produccionTotal": 1250,
        "unidad": "kg",
        "calidadValidada": true
      },
      {
        "id": 2,
        "nombre": "Telares",
        "estadoProceso": "ESPERANDO_CALIDAD",
        "produccionTotal": 0,
        "unidad": "m",
        "calidadValidada": false
      }
    ],
    "estadoTurno": "EN_PROCESO",
    "siguienteAccion": "IR_A_PROCESO",
    "puedeCerrarTurno": false,
    "razonesBloqueoCierre": ["Existen procesos pendientes: Telares"]
  }
}

Get Active Shift Log

GET /api/bitacora/activa

Returns the currently active shift log, or null if no shift is open.

Response

Returns the active bitácora object or null.

Open Shift Log

POST /api/bitacora/abrir

Permission: MANAGE_QUALITY Opens a new shift log for the current shift. Automatically determines the shift (T1/T2/T3) based on current time.

Business Rules

Only one shift log can be active at a time
Shift and operational date are auto-calculated
Out-of-hours flag is set if opened outside normal shift time
Inspector is set from authenticated user

Implementation

From bitacora.controller.js:127:

const { turno, fechaOperativa } = getTurnoActual();
const inspector = req.user.nombre || req.user.username;

// Detect out-of-hours opening
const now = new Date();
const hours = now.getHours();
let fueraDeHorario = false;
if (turno === 'T1' && (hours < 7 || hours >= 15)) fueraDeHorario = true;
if (turno === 'T2' && (hours < 15 || hours >= 23)) fueraDeHorario = true;
if (turno === 'T3' && (hours >= 7 && hours < 23)) fueraDeHorario = true;

Example Request

cURL

curl -X POST https://api.example.com/api/bitacora/abrir \
  -H "Authorization: Bearer <token>"

Example Response

{
  "success": true,
  "data": {
    "id": 43,
    "turno": "T2",
    "fecha_operativa": "2026-03-06",
    "inspector": "María López",
    "estado": "ABIERTA",
    "fuera_de_horario": false,
    "fecha_apertura": "2026-03-06T15:05:00Z"
  }
}

Error Responses

400 Bad Request

Returned when a shift log is already open:

{
  "success": false,
  "error": "Ya existe una bitácora abierta para este turno."
}

Close Shift Log

POST /api/bitacora/:id/cerrar

Permission: MANAGE_QUALITY Closes a shift log after validating all processes are complete.

Path Parameters

integer

required

Bitácora ID to close

Closure Validation

From bitacora.service.js:106:

Process Validation: Every process must have quality samples and production data
Personnel Check: Processes with activity must have assigned personnel
Downtime Validation: Total downtime cannot exceed programmed time
Rejection Detection: If quality rejections exist, state moves to REVISION
Observation Requirement: Deviations require detailed observations

Response

message

string

Success or revision message

estado

string

Final state: CERRADA or REVISION

Example Request

cURL

curl -X POST https://api.example.com/api/bitacora/43/cerrar \
  -H "Authorization: Bearer <token>"

Example Response

{
  "success": true,
  "data": {
    "message": "Bitácora enviada a REVISIÓN debido a desviaciones detectadas.",
    "estado": "REVISION"
  }
}

Get Process Data

GET /api/bitacora/proceso-data?bitacora_id={id}&proceso_id={pid}

Retrieves all data entered for a specific process in a shift.

Query Parameters

bitacora_id

integer

required

Bitácora ID

proceso_id

integer

required

Process ID (1-9)

ultimo_turno

boolean

If true, retrieve data from the last closed shift for this process (for parameter inheritance)

Response

no_operativo

boolean

Whether the process was marked as non-operational this shift

planificado

object

Planned orders and personnel from weekly planning (if available)

muestras

array

Quality samples recorded

produccion

array

Production records by order and machine

desperdicio

array

Waste/scrap records

parametros_operativos

object

Process-specific operational parameters (e.g., temperatures, speeds)

solo_lectura

boolean

Whether the shift is closed and data is read-only

Save Process Data

POST /api/bitacora/guardar-proceso

Permission: MANAGE_PRODUCTION Saves production and quality data for a process.

Request Body

bitacora_id

integer

required

Target bitácora ID

proceso_id

integer

required

Process ID (1-9)

no_operativo

boolean

Mark process as non-operational (e.g., maintenance, no orders)

motivo_no_operativo

string

Reason for non-operation (required if no_operativo = true)

produccion

array

Production records:

[
  {
    "orden_id": 12345,
    "maquina": "TEL-01",
    "cantidad": 500,
    "unidad": "m"
  }
]

muestras

array

Quality samples:

[
  {
    "parametro": "Ancho",
    "valor": "105",
    "resultado": "Cumple"
  }
]

observaciones

string

General observations or notes

Example Request

cURL

curl -X POST https://api.example.com/api/bitacora/guardar-proceso \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "bitacora_id": 43,
    "proceso_id": 2,
    "produccion": [
      {
        "orden_id": 12345,
        "maquina": "TEL-03",
        "cantidad": 850,
        "unidad": "m"
      }
    ],
    "muestras": [
      {
        "parametro": "Ancho",
        "valor": "105",
        "resultado": "Cumple"
      },
      {
        "parametro": "Construcción",
        "valor": "10x10",
        "resultado": "Cumple"
      }
    ],
    "observaciones": "Producción normal sin incidentes."
  }'

Get Time Summary

GET /api/bitacora/resumen-tiempo?bitacora_id={id}&proceso_id={pid}

Calculates programmed time, downtime, and effective time for a process.

Query Parameters

bitacora_id

integer

required

Bitácora ID

proceso_id

integer

required

Process ID

Response

tiempo_programado

integer

Programmed time in minutes (typically 480 for an 8-hour shift)

total_paros

integer

Total downtime in minutes

tiempo_efectivo

integer

Effective production time = programmed - downtime

Example Response

{
  "success": true,
  "data": {
    "tiempo_programado": 480,
    "total_paros": 45,
    "tiempo_efectivo": 435
  }
}

Best Practices

Quality-First Workflow: Always validate quality samples before recording production. The system enforces this requirement.

Closure Validation: Ensure all processes have complete data before attempting to close a shift. Missing data will block closure.

Audit Trail: All actions are automatically logged with user, timestamp, and changes. This supports regulatory compliance.

Production Orders - Manage production orders
Incidents - Report shift incidents
Quality Control - Quality sample management
Planning - Weekly production planning

Authentication

Production

Quality Control

Resources

Personnel & Groups

Dashboard & Analytics

Operations

System

​Bitácora (Shift Log) API

​Authentication

​Core Concepts

​Get Current State

​Response Fields

​Example Request

​Example Response

​Get Active Shift Log

​Response

​Open Shift Log

​Business Rules

​Implementation

​Example Request

​Example Response

​Error Responses

​Close Shift Log

​Path Parameters

​Closure Validation

​Response

​Example Request

​Example Response

​Get Process Data

​Query Parameters

​Response

​Save Process Data

​Request Body

​Example Request

​Get Time Summary

​Query Parameters

​Response

​Example Response

​Best Practices

​Related Endpoints

Build docs developers (and LLMs) love

Bitácora (Shift Log) API

Authentication

Core Concepts

Get Current State

Response Fields

Example Request

Example Response

Get Active Shift Log

Response

Open Shift Log

Business Rules

Implementation

Example Request

Example Response

Error Responses

Close Shift Log

Path Parameters

Closure Validation

Response

Example Request

Example Response

Get Process Data

Query Parameters

Response

Save Process Data

Request Body

Example Request

Get Time Summary

Query Parameters

Response

Example Response

Best Practices

Related Endpoints