Schedule Management

Create Schedule from Reservation

curl -X POST http://localhost:8000/api/v1/crear-horario-desde-programacion/PROG001

{
  "success": true,
  "horario": {
    "id": "H_PROG001_20250617_151314",
    "tipo": "normal",
    "asignatura": {
      "id": "A001",
      "nombre": "Álgebra Lineal"
    },
    "aula": {
      "id": "AU001",
      "nombre": "Aula 101"
    },
    "docente": {
      "id": "D001",
      "nombre": "Dr. García"
    },
    "start_time": "07:00",
    "end_time": "09:00",
    "dia": "Lunes",
    "created_at": "2025-06-17T15:13:14.191244",
    "estado": "confirmado"
  },
  "programacion_actualizada": {
    "id": "PROG001",
    "estado": "ocupado",
    "horario_id": "H_PROG001_20250617_151314",
    "fecha_confirmacion": "2025-06-17T15:13:14.191244"
  },
  "tipo_horario": "normal"
}

POST /crear-horario-desde-programacion/

Creates a formal schedule (horario) from a reservation (programacion) using the Builder design pattern.

How It Works

Validates programacion - Must exist and be in reservado state
Loads related entities - Retrieves course, classroom, professor, and campus data
Determines schedule type - Based on course type (normal, laboratorio, virtual, bloqueo)
Builds schedule object - Uses HorarioFacade and Builder pattern to create validated schedule
Updates programacion - Changes state to ocupado and links to created schedule

This endpoint implements the Builder design pattern through the HorarioFacade, providing structured schedule creation with validation.

Path Parameters

programacion_id

string

required

ID of the programacion (reservation) to convert into a schedule. Must have status reservado.Example: "PROG001"

Response Fields

success

boolean

Indicates if schedule was created successfully

horario

object

The created schedule object

Show properties

string

Unique schedule ID (format: H_{programacion_id}_{timestamp})

tipo

string

Schedule type: normal, laboratorio, virtual, or bloqueo

asignatura

object

Course information

aula

object

Classroom information

docente

object

Professor information

sede

object

Campus information

start_time

string

Start time

end_time

string

End time

dia

string

Day of week

created_at

string

ISO 8601 timestamp when schedule was created

estado

string

Schedule state (typically confirmado)

programacion_actualizada

object

The updated programacion with new status and schedule reference

Show properties

string

Programacion ID

estado

string

Updated to ocupado

horario_id

string

ID of the created schedule

fecha_confirmacion

string

ISO 8601 timestamp of confirmation

tipo_horario

string

Type of schedule created

Create Complete Semester Schedule

curl -X POST 'http://localhost:8000/api/v1/crear-horario-completo-semestre/1?validar_conjunto=true'

{
  "success": true,
  "semestre": 1,
  "total_horarios": 15,
  "horarios": [
    {
      "id": "H_PROG001_20250617_151314",
      "tipo": "normal",
      "asignatura": {"id": "A001", "nombre": "Álgebra Lineal"},
      "aula": {"id": "AU001", "nombre": "Aula 101"},
      "start_time": "07:00",
      "end_time": "09:00",
      "dia": "Lunes"
    }
  ],
  "errores": [],
  "estadisticas": {
    "total_schedules": 15,
    "by_type": {
      "normal": 10,
      "laboratorio": 5
    },
    "by_day": {
      "Lunes": 3,
      "Martes": 3,
      "Miércoles": 3,
      "Jueves": 3,
      "Viernes": 3
    }
  },
  "validacion_conjunto": "OK"
}

POST /crear-horario-completo-semestre/

Creates a complete schedule for an entire semester by processing all reserved programaciones.

How It Works

Queries programaciones - Finds all programaciones with status reservado for the semester
Creates individual schedules - Calls schedule creation for each programacion
Validates as a set - Optionally validates all schedules together for conflicts
Generates statistics - Computes statistics using the Facade pattern
Returns results - Includes all created schedules, errors, and statistics

This endpoint processes multiple reservations. If validar_conjunto=true, any validation failure will cause the entire operation to fail.

Path Parameters

semestre

integer

required

Semester number (1-10) to create schedules forExample: 1

Query Parameters

validar_conjunto

boolean

default:"true"

Whether to validate all schedules together for conflicts. Set to false to skip collective validation.Example: true

Response Fields

success

boolean

Overall success status

semestre

integer

Semester number processed

total_horarios

integer

Number of schedules successfully created

horarios

array

List of all created schedule objects (same structure as individual schedule)

errores

array

List of error messages for any programaciones that failed to convert to schedules

estadisticas

object

Statistics about the created schedules

Show properties

total_schedules

integer

Total count of schedules

by_type

object

Breakdown by schedule type (normal, laboratorio, virtual, bloqueo)

by_day

object

Breakdown by day of week

validacion_conjunto

string

Result of collective validation: “OK” if validation passed or “No validado” if skipped

List Schedules by Semester

curl http://localhost:8000/api/v1/horarios-por-semestre/1

{
  "semestre": 1,
  "total_horarios": 15,
  "horarios": [
    {
      "horario_id": "H_PROG001_20250617_151314",
      "programacion_id": "PROG001",
      "aula_id": "AU001",
      "asignatura_id": "A001",
      "docente_id": "D001",
      "fecha": "2024-07-22",
      "dia": "Lunes",
      "hora_inicio": "07:00",
      "hora_fin": "09:00",
      "semestre": 1,
      "estado": "ocupado",
      "fecha_confirmacion": "2025-06-17T15:13:14.191244"
    }
  ]
}

GET /horarios-por-semestre/

Retrieves all confirmed schedules for a specific semester.

This endpoint returns programaciones with status ocupado (confirmed schedules), not reservado (pending reservations).

Path Parameters

semestre

integer

required

Semester number to queryExample: 1

Response Fields

semestre

integer

The queried semester number

total_horarios

integer

Count of confirmed schedules

horarios

array

List of schedule/programacion objects with status ocupado

Show schedule object

horario_id

string

ID of the created schedule

programacion_id

string

ID of the underlying programacion

aula_id

string

Classroom ID

asignatura_id

string

Course ID

docente_id

string

Professor ID

fecha

string

Session date

dia

string

Day of week

hora_inicio

string

Start time

hora_fin

string

End time

semestre

integer

Semester number

estado

string

Always ocupado for confirmed schedules

fecha_confirmacion

string

ISO 8601 timestamp when schedule was confirmed

Complete Semester Workflow

End-to-End Example

import requests
import time

BASE_URL = "http://localhost:8000/api/v1"
semester = 1

# Step 1: Create multiple reservations
reservations = [
    {"asignatura_id": "A001", "aula_id": "AU001", "dia": "Lunes", "hora_inicio": "07:00", "hora_fin": "09:00"},
    {"asignatura_id": "A002", "aula_id": "AU002", "dia": "Martes", "hora_inicio": "10:00", "hora_fin": "12:00"},
    {"asignatura_id": "A003", "aula_id": "AU003", "dia": "Miércoles", "hora_inicio": "14:00", "hora_fin": "16:00"},
]

for res in reservations:
    res.update({
        "fecha": "22/07/2024",
        "cantidad_estudiantes": 30,
        "semestre": semester,
        "docente_id": "D001",
        "id_usuario": "USR001"
    })
    
    response = requests.post(f"{BASE_URL}/reservar-aula", json=res)
    if response.json()['success']:
        print(f"Reserved {res['asignatura_id']}")

time.sleep(1)

# Step 2: Create complete semester schedule
response = requests.post(
    f"{BASE_URL}/crear-horario-completo-semestre/{semester}",
    params={'validar_conjunto': True}
)

result = response.json()

if result['success']:
    print(f"\nCreated {result['total_horarios']} schedules")
    print(f"Statistics: {result['estadisticas']}")
    print(f"Validation: {result['validacion_conjunto']}")
    
    # Step 3: Retrieve all schedules for verification
    schedules = requests.get(f"{BASE_URL}/horarios-por-semestre/{semester}").json()
    print(f"\nVerified {schedules['total_horarios']} confirmed schedules")
else:
    print(f"Failed: {result.get('error')}")
    print(f"Errors: {result.get('errores', [])}")

Schedule Types

Schedules are automatically categorized by course type:

Course Type	Schedule Type	Description
`teorica`	`normal`	Standard lecture schedule
`laboratorio`	`laboratorio`	Laboratory session schedule
`virtual`	`virtual`	Online/virtual class schedule
`bloqueo`	`bloqueo`	Blocking schedule (reserved time)

Design Patterns

These endpoints implement several design patterns:

Builder Pattern: Schedule creation through HorarioFacade
Facade Pattern: Simplified interface to complex schedule validation and creation
Chain of Responsibility: Constraint validation chain

See source code for implementation details:

src/core/schedules/facade/horario_facade.py
src/services/horario_completo_service.py

Endpoints

Create Schedule from Reservation

POST /crear-horario-desde-programacion/

How It Works

Path Parameters

Response Fields

Create Complete Semester Schedule

POST /crear-horario-completo-semestre/

How It Works

Path Parameters

Query Parameters

Response Fields

List Schedules by Semester

GET /horarios-por-semestre/

Path Parameters

Response Fields

Complete Semester Workflow

End-to-End Example

Schedule Types

Design Patterns

Build docs developers (and LLMs) love

Endpoints

​Create Schedule from Reservation

​POST /crear-horario-desde-programacion/

​How It Works

​Path Parameters

​Response Fields

​Create Complete Semester Schedule

​POST /crear-horario-completo-semestre/

​How It Works

​Path Parameters

​Query Parameters

​Response Fields

​List Schedules by Semester

​GET /horarios-por-semestre/

​Path Parameters

​Response Fields

​Complete Semester Workflow

​End-to-End Example

​Schedule Types

​Design Patterns

Build docs developers (and LLMs) love

Create Schedule from Reservation

POST /crear-horario-desde-programacion/

How It Works

Path Parameters

Response Fields

Create Complete Semester Schedule

POST /crear-horario-completo-semestre/

How It Works

Path Parameters

Query Parameters

Response Fields

List Schedules by Semester

GET /horarios-por-semestre/

Path Parameters

Response Fields

Complete Semester Workflow

End-to-End Example

Schedule Types

Design Patterns