Skip to main content

​
Get Available Classrooms

curl -X POST http://localhost:8000/api/v1/aulas-disponibles \
  -H "Content-Type: application/json" \
  -d '{
    "asignatura_id": "A001",
    "hora_inicio": "07:00",
    "hora_fin": "09:00",
    "dia": "Lunes",
    "cantidad_estudiantes": 30,
    "semestre": 1
  }'

{
  "asignatura": {
    "id": "A001",
    "nombre": "Álgebra Lineal",
    "tipo": "teorica"
  },
  "horario_solicitado": {
    "dia": "Lunes",
    "hora_inicio": "07:00",
    "hora_fin": "09:00",
    "cantidad_estudiantes": 30,
    "semestre": 1
  },
  "aulas_disponibles": [
    {
      "id": "AU001",
      "nombre": "Aula 101",
      "tipo": "teorica",
      "capacidad": 40,
      "sede": {
        "id": "S001",
        "nombre": "Sede Principal"
      },
      "recursos": [
        {
          "id": "R001",
          "nombre": "Proyector"
        },
        {
          "id": "R002",
          "nombre": "Pizarra Digital"
        }
      ]
    }
  ],
  "aulas_no_disponibles": [
    {
      "id": "AU003",
      "nombre": "Aula 201",
      "razon": "Aula ocupada o reservada en el horario 07:00-09:00 el Lunes"
    },
    {
      "id": "AU005",
      "nombre": "Aula 102",
      "razon": "Capacidad insuficiente: requiere 30 estudiantes, capacidad disponible 25"
    }
  ],
  "total_disponibles": 1,
  "total_no_disponibles": 2,
  "error": null
}

​
POST /aulas-disponibles

Obtains available classrooms for a course at a specific time, applying all system constraints.

​
How It Works

The endpoint performs a multi-step evaluation:
  1. Validates the course exists and is active
  2. Applies capacity constraint - filters classrooms with sufficient capacity
  3. Checks compatibility - ensures classroom type matches course requirements (teorica, laboratorio, virtual)
  4. Verifies availability - checks no conflicting reservations exist for the time slot
  5. Returns categorized results - available and unavailable classrooms with reasons

​
Request Body

​
asignatura_id
string
required
ID of the course/subject. Must match an existing course in the system.Example: "A001" for Álgebra Lineal
​
hora_inicio
string
required
Start time in 24-hour format HH:MM. Must be valid time between 00:00 and 23:59.Example: "07:00"
​
hora_fin
string
required
End time in 24-hour format HH:MM. Must be after hora_inicio.Example: "09:00"
​
dia
string
required
Day of the week in Spanish. Must be one of: Lunes, Martes, Miércoles, Jueves, Viernes, Sábado, Domingo.Example: "Lunes"
​
cantidad_estudiantes
integer
required
Number of students. Must be greater than 0.Example: 30
​
semestre
integer
required
Academic semester. Must be between 1 and 10.Example: 1

​
Response Fields

​
asignatura
object
Information about the requested course.
​
horario_solicitado
object
Echo of the requested time slot parameters.
​
aulas_disponibles
array
List of classrooms that meet all requirements and are available.
​
aulas_no_disponibles
array
List of classrooms that don’t meet requirements, with reason for each.
​
total_disponibles
integer
Count of available classrooms
​
total_no_disponibles
integer
Count of unavailable classrooms
​
error
string | null
Error message if course not found, otherwise null

​
Common Use Cases

​
Finding Large Classrooms

# Request with high student count to filter for large rooms
payload = {
    "asignatura_id": "A001",
    "cantidad_estudiantes": 50,  # Only large classrooms will qualify
    "hora_inicio": "14:00",
    "hora_fin": "16:00",
    "dia": "Miércoles",
    "semestre": 2
}

​
Checking Weekly Availability

import requests

days = ["Lunes", "Martes", "Miércoles", "Jueves", "Viernes"]
availability = {}

for day in days:
    response = requests.post(
        "http://localhost:8000/api/v1/aulas-disponibles",
        json={
            "asignatura_id": "A001",
            "hora_inicio": "10:00",
            "hora_fin": "12:00",
            "dia": day,
            "cantidad_estudiantes": 30,
            "semestre": 1
        }
    )
    data = response.json()
    availability[day] = data['total_disponibles']

print("Weekly availability:", availability)

​
Understanding Constraints

​
Capacity Constraint

Classrooms must have capacity >= requested students. Example rejection: 
{
  "razon": "Capacidad insuficiente: requiere 30 estudiantes, capacidad disponible 25"
}

​
Compatibility Constraint

Course type must match classroom type:
Course TypeCompatible Classroom Types
teoricateorica
laboratoriolaboratorio
virtualvirtual

​
Availability Constraint

Classroom must not have overlapping reservations. The system checks:
  • Same day of week
  • Overlapping time periods
  • Active reservations (status: reservado or ocupado)
Availability is checked across ALL semesters. A Monday 07:00-09:00 reservation will block that classroom for all courses on Monday mornings, regardless of semester.

Build docs developers (and LLMs) love

Get started for freeTalk to us