Planning API

The Planning API manages weekly production planning, including order scheduling, personnel assignments, and deviation tracking against planned vs. actual execution.

Authentication

Read operations: VIEW_PRODUCTION permission
Planning operations: ASSIGN_OPERATIONS permission
Deviation tracking: MANAGE_PRODUCTION permission

Get Weekly Plan

GET /api/planning/week/:anio/:semana

Permission: VIEW_PRODUCTION Retrieves the production plan for a specific week.

Path Parameters

anio

integer

required

Year (e.g., 2026)

semana

integer

required

ISO week number (1-53)

Response

integer

Plan ID

anio

integer

Year

semana

integer

Week number

estado

string

Plan state: Borrador, Publicado

ordenes

array

Planned production orders for the week

Show orden properties

integer

Assignment ID

orden_id

integer

Production order ID

proceso_id

integer

Target process ID

turno

string

Planned shift: T1, T2, T3

dia_semana

integer

Day of week (1=Monday, 7=Sunday)

cantidad_planificada

number

Planned production quantity

personal

array

Personnel assignments for the week

Show assignment properties

integer

Assignment ID

persona_id

integer

Person ID

proceso_id

integer

Assigned process ID

turno

string

Assigned shift

dia_semana

integer

Day of week

Example Request

cURL

curl -X GET https://api.example.com/api/planning/week/2026/10 \
  -H "Authorization: Bearer <token>"

JavaScript

const response = await fetch('/api/planning/week/2026/10', {
  headers: { 'Authorization': `Bearer ${token}` }
});
const plan = await response.json();

Example Response

{
  "id": 5,
  "anio": 2026,
  "semana": 10,
  "estado": "Publicado",
  "ordenes": [
    {
      "id": 101,
      "orden_id": 12345,
      "proceso_id": 1,
      "turno": "T1",
      "dia_semana": 1,
      "cantidad_planificada": 1500
    },
    {
      "id": 102,
      "orden_id": 12346,
      "proceso_id": 2,
      "turno": "T1",
      "dia_semana": 2,
      "cantidad_planificada": 3000
    }
  ],
  "personal": [
    {
      "id": 201,
      "persona_id": 42,
      "proceso_id": 1,
      "turno": "T1",
      "dia_semana": 1
    }
  ]
}

404 Response

If no plan exists for the specified week:

{
  "message": "No existe planificación para esta semana",
  "plan": null
}

Create Plan

POST /api/planning/create

Permission: ASSIGN_OPERATIONS Creates a new weekly production plan.

Request Body

anio

integer

required

Year

semana

integer

required

ISO week number (1-53)

Response

Returns the newly created plan object with status Borrador.

Example Request

cURL

curl -X POST https://api.example.com/api/planning/create \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "anio": 2026,
    "semana": 11
  }'

Assign Order

POST /api/planning/assign-order

Permission: ASSIGN_OPERATIONS Assigns a production order to a specific day, shift, and process.

Request Body

plan_id

integer

required

Plan ID

orden_id

integer

required

Production order ID

proceso_id

integer

required

Process ID (1-9)

turno

string

required

Shift: T1, T2, or T3

dia_semana

integer

required

Day of week (1=Monday, 7=Sunday)

cantidad_planificada

number

required

Planned production quantity

Example Request

cURL

curl -X POST https://api.example.com/api/planning/assign-order \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": 5,
    "orden_id": 12347,
    "proceso_id": 3,
    "turno": "T2",
    "dia_semana": 3,
    "cantidad_planificada": 2500
  }'

Update Order Assignment

POST /api/planning/update-order

Permission: ASSIGN_OPERATIONS Updates an existing order assignment.

Request Body

integer

required

Assignment ID

plan_id

integer

required

Plan ID

Plus any fields from assign-order to update.

Delete Order Assignment

POST /api/planning/delete-order

Permission: ASSIGN_OPERATIONS Removes an order from the plan.

Request Body

integer

required

Assignment ID to delete

plan_id

integer

required

Plan ID

Assign Personnel

POST /api/planning/assign-personnel

Permission: ASSIGN_OPERATIONS Assigns a person to a process, shift, and day.

Request Body

plan_id

integer

required

Plan ID

persona_id

integer

required

Person ID

proceso_id

integer

required

Process ID

turno

string

required

Shift: T1, T2, T3

dia_semana

integer

required

Day of week (1-7)

Example Request

cURL

curl -X POST https://api.example.com/api/planning/assign-personnel \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": 5,
    "persona_id": 42,
    "proceso_id": 2,
    "turno": "T1",
    "dia_semana": 2
  }'

Update Personnel Assignment

POST /api/planning/update-personnel

Permission: ASSIGN_OPERATIONS Updates an existing personnel assignment.

Delete Personnel Assignment

POST /api/planning/delete-personnel

Permission: ASSIGN_OPERATIONS Removes a personnel assignment from the plan.

Publish Plan

POST /api/planning/publish

Permission: ASSIGN_OPERATIONS Publishes a plan, making it visible to production operators and locking further modifications.

Request Body

integer

required

Plan ID to publish

Business Rules

Once published, a plan cannot be unpublished (create a new plan instead)
Published plans are used by the Bitácora system for shift inheritance
All personnel and order assignments should be finalized before publishing

Example Request

cURL

curl -X POST https://api.example.com/api/planning/publish \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"id": 5}'

Record Deviation

POST /api/planning/deviation

Permission: MANAGE_PRODUCTION Records a deviation from the planned schedule.

Request Body

plan_id

integer

required

Plan ID

bitacora_id

integer

required

Bitácora ID where deviation occurred

orden_id

integer

required

Order ID affected

proceso_id

integer

required

Process ID

motivo_id

integer

required

Deviation reason ID (from motivos catalog)

cantidad_planificada

number

required

Originally planned quantity

cantidad_real

number

required

Actual produced quantity

comentarios

string

Additional comments or context

Example Request

cURL

curl -X POST https://api.example.com/api/planning/deviation \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": 5,
    "bitacora_id": 43,
    "orden_id": 12345,
    "proceso_id": 1,
    "motivo_id": 2,
    "cantidad_planificada": 1500,
    "cantidad_real": 1200,
    "comentarios": "Paro no programado por falla eléctrica"
  }'

Get Deviation Reasons

GET /api/planning/motivos-desviacion

Permission: VIEW_PRODUCTION Returns the catalog of deviation reasons.

Example Response

[
  {"id": 1, "motivo": "Falta de materia prima"},
  {"id": 2, "motivo": "Falla de equipo"},
  {"id": 3, "motivo": "Ausencia de personal"},
  {"id": 4, "motivo": "Cambio de prioridad"},
  {"id": 5, "motivo": "Problema de calidad"}
]

Get Deviations

GET /api/planning/desviaciones?bitacora_id={id}

Permission: VIEW_PRODUCTION Returns all deviations for a specific shift.

Query Parameters

bitacora_id

integer

required

Bitácora ID

Get Plan KPIs

GET /api/planning/kpi/:plan_id

Permission: VIEW_PRODUCTION Calculates performance metrics for a completed week.

Path Parameters

plan_id

integer

required

Plan ID

Response

cumplimiento_global

number

Overall plan fulfillment percentage (0-100)

total_planificado

number

Total planned production across all orders

total_producido

number

Total actual production

ordenes_completadas

integer

Number of orders meeting 100% target

ordenes_totales

integer

Total orders in plan

desviaciones_count

integer

Number of deviations recorded

por_proceso

array

Fulfillment breakdown by process

Example Response

{
  "cumplimiento_global": 92.5,
  "total_planificado": 50000,
  "total_producido": 46250,
  "ordenes_completadas": 8,
  "ordenes_totales": 10,
  "desviaciones_count": 3,
  "por_proceso": [
    {
      "proceso_id": 1,
      "proceso_nombre": "Extrusor PP",
      "cumplimiento": 98.2
    },
    {
      "proceso_id": 2,
      "proceso_nombre": "Telares",
      "cumplimiento": 87.5
    }
  ]
}

Planning Workflow

Create Plan

Create a plan for next week (e.g., Week 11)

Assign Orders

Assign production orders to specific days, shifts, and processes

Assign Personnel

Assign available personnel to cover all shifts and processes

Review & Adjust

Review capacity, balance workload, adjust as needed

Publish

Publish the plan to make it active and visible to operators

Execute

During the week, operators see planned orders in their bitácoras

Track Deviations

Record deviations when actual differs from plan

Analyze KPIs

After week completion, review KPIs to improve future planning

Best Practices

Advance Planning: Create plans at least 3-5 days before the target week to allow for material procurement and personnel coordination.

Capacity Validation: Ensure planned quantities are realistic given:

Machine capacity and availability
Personnel skill levels and availability
Material lead times
Maintenance schedules

Deviation Tracking: Always record deviations with specific reasons. This data drives continuous improvement and helps identify systemic bottlenecks.

Bitácora API - Shift execution against plan
Production Orders - Order management
Personnel API - Personnel management

Authentication

Production

Quality Control

Resources

Personnel & Groups

Dashboard & Analytics

Operations

System

​Planning API

​Authentication

​Get Weekly Plan

​Path Parameters

​Response

​Example Request

​Example Response

​Create Plan

​Request Body

​Response

​Example Request

​Assign Order

​Request Body

​Example Request

​Update Order Assignment

​Request Body

​Delete Order Assignment

​Request Body

​Assign Personnel

​Request Body

​Example Request

​Update Personnel Assignment

​Delete Personnel Assignment

​Publish Plan

​Request Body

​Business Rules

​Example Request

​Record Deviation

​Request Body

​Example Request

​Get Deviation Reasons

​Example Response

​Get Deviations

​Query Parameters

​Get Plan KPIs

​Path Parameters

​Response

​Example Response

​Planning Workflow

​Best Practices

​Related Endpoints

Build docs developers (and LLMs) love

Planning API

Authentication

Get Weekly Plan

Path Parameters

Response

Example Request

Example Response

Create Plan

Request Body

Response

Example Request

Assign Order

Request Body

Example Request

Update Order Assignment

Request Body

Delete Order Assignment

Request Body

Assign Personnel

Request Body

Example Request

Update Personnel Assignment

Delete Personnel Assignment

Publish Plan

Request Body

Business Rules

Example Request

Record Deviation

Request Body

Example Request

Get Deviation Reasons

Example Response

Get Deviations

Query Parameters

Get Plan KPIs

Path Parameters

Response

Example Response

Planning Workflow

Best Practices

Related Endpoints