La API de las sesiones — recuperar las sesiones de cualquier fecha

La API de las sesiones: GET /api/schedules/lessons/{datesrange} es el punto de acceso todoterreno para recuperar las sesiones realmente fechadas de sus horarios — cualquier fecha o conjunto de fechas, filtrado sobre las entidades deseadas, con o sin las estructuras subyacentes, las ausencias y las sustituciones, los horarios o las simples periodos de rejilla. Es el punto de partida de la mayoría de las integraciones.

Cuando algo fuera de Omniscol necesita saber qué pasa, y cuándo, es a este punto de acceso al que se llama:

GET /api/schedules/lessons/{datesrange}

Devuelve las sesiones fechadas de sus horarios — cada sesión colocada en su fecha real — para las fechas y las entidades solicitadas. Casi toda integración (una intranet, un ETL, una herramienta de socio) parte de ahí. Esta página recorre las palancas que hacen de él un solo punto de acceso para muchos usos.

Sesiones vs estructuras

Dos puntos de acceso, dos roles:

• GET /api/schedules/lessons/{datesrange} — las sesiones: cada sesión colocada en una fecha real, con su asignatura, sus profesores, su aula, su grupo y su duración. Es lo que se lee para saber quién está dónde y cuándo.
• GET /api/schedules/ — las estructuras: los horarios publicados en sí mismos (clases, asignaturas, sedes, la rejilla). Se lee cuando se necesita el modelo subyacente en lugar de las sesiones fechadas.

También se pueden plegar las estructuras dentro de la llamada de las sesiones con with_timetables=true (véase más abajo): una sola petición devuelve entonces ambas.

Elegir las fechas

{datesrange} se escribe en YYYYMMDD y se quiere deliberadamente flexible:

La forma dispersa (separada por comas) es lo que convierte una pregunta como «estos tres lunes» en una sola llamada.

Apuntar a lo que necesita

Un filter restringe la petición a las entidades que importan — la misma gramática de filtro que los puntos de acceso de disponibilidad (Consultas avanzadas):

• una simple lista de identificadores — {"classes":["3a","3b"]},
• un comodín — {"teachers":"*"},
• una correspondencia de campo simple — {"classrooms":[{"site":"nord"}]},
• o un $where estructurado — {"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}.

El resultado se agrupa por tipo de filtro, y luego por identificador de entidad — por ejemplo schedules.classes.3a.courses[], schedules.teachers.j-doe.courses[].

Otros dos ajustes encuadran la extracción, y un último la limita:

• timetables_restrict / timetables_exclude — limitar o excluir identificadores de horario (cadena, CSV o array).
• limit — limitar el número de sesiones devueltas por filtro.

A qué se parece una sesión

Cada entrada de courses[] es una sesión colocada:

{
  "position": { "day": "2026-10-05", "period": 0, "start": "8:15", "end": "9:10" },
  "duration": 2,
  "subject": "maths",
  "teachers": ["j-doe"],
  "classroom": "nord:B12",
  "class": "3a",
  "schedid": "3"
}

• position.day es la fecha de la sesión.
• position.period es el índice de la sesión en la rejilla del horario — presente para las sesiones colocadas en la rejilla. Una sesión fuera de rejilla (con sus propios start/end explícitos, fuera de las franjas regulares) lleva start/end en su lugar, sin period.
• position.start / position.end (horarios) acompañan siempre a una sesión fuera de rejilla, y se añaden a las sesiones de rejilla cuando pasa with_hours=true (horarios precalculados). Actívelo cuando su sistema destino necesite las horas de reloj en lugar del índice de rejilla.

Ausencias, cancelaciones y sustituciones

Por defecto, el punto de acceso consolida las ausencias: un profesor ausente se retira de la sesión, y una sesión sin profesor restante se considera cancelada y se descarta. Varios indicadores cambian esto:

• without_absences — ignorar por completo las ausencias; devolver la rejilla planificada en bruto.
• with_absences — añadir las ausencias en bruto del periodo junto a las sesiones.
• with_cancelcourses — conservar las sesiones canceladas (todos los profesores ausentes) en lugar de descartarlas.
• with_studentcancelcourses — conservar únicamente las sesiones canceladas por la ausencia de un alumno.
• with_removedcourses — devolver las sesiones retiradas (exclusivo con with_cancelcourses).
• without_teacher_consolidation — mantener a los profesores ausentes en la lista teachers de cada sesión en lugar de retirarlos.
• without_holidays — no inyectar las vacaciones en el rango.

Por defecto, cuando se ha designado un sustituto para una ausencia, reemplaza sencillamente al profesor ausente en la lista teachers de la sesión — la sustitución es transparente, sin campo adicional. Pase with_cancelcourses o without_teacher_consolidation y la sesión lleva además un bloque substitutes (el identificador del sustituto, el motivo de ausencia y la ausencia que lo impuso), para ver quién ha sido reemplazado y por qué en la misma carga útil.

Estructuras y directorios

Adjunte los datos de referencia útiles, en la misma llamada:

• with_timetables=true — las estructuras en bruto de los horarios que han servido para calcular las sesiones (clases, asignaturas, rejilla, por identificador). Actívelo para resolver los identificadores; déjelo desactivado para una respuesta compacta.
• with_entities=true — nombre/código ligeros (y campos de nombre de persona) de las entidades del resultado.
• with_teachers / with_all_teachers — los profesores utilizados en las sesiones, o todos los profesores del horario y del directorio.
• with_students — los alumnos, con sus colocaciones por fecha.
• with_events=true — los eventos fuera de rejilla (consejos, reuniones de padres y profesores…) sobre el mismo rango.

Un tirón ETL nocturno

Recuperar una semana de sesiones para todas las clases, con los horarios, y cargarla en su sistema de información:

curl -G "https://su-escuela.omniscol.com/api/schedules/lessons/20261005-20261011" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode 'filter={"classes":"*"}' \
  --data-urlencode "with_hours=true"

La respuesta agrupa las sesiones bajo schedules.classes.<id>.courses[]. Las ausencias ya están consolidadas: lo que carga refleja el horario real y actualizado — añada with_absences=true si quiere registrar también la razón de un cambio.

Empujar hacia Omniscol

La integración funciona también en el otro sentido — para mantener Omniscol alineado con una fuente de verdad externa. Estos puntos de acceso existen únicamente para esta sincronización externa; la interfaz de Omniscol no los llama nunca por sí misma:

• POST /api/external/classes (os_external_classes_post) — actualizar clases existentes (nombre, sede, nivel, aula, efectivo) desde una carga útil indexada por identificador de clase. Actualiza las clases conocidas; no crea nuevas. Ponga un campo a null para borrarlo (el nombre de la clase exceptuado — una clase conserva su nombre).
• POST /api/external/teachers (os_external_teachers_post) — insertar o actualizar profesores por identificador, a la vez en los horarios y en el directorio (creando el usuario con el rol de profesor y un login autogenerado si es necesario). Las variantes DELETE retiran una clase o un profesor.
• POST /api/admin/subjects/custom (os_admin_subjects-custom_post) — cargar un catálogo de asignaturas personalizadas. El cuerpo es { "subjects": [ … ], "replace": false, "nodoubles": true }: incremental por defecto, replace: true para un refresco completo, nodoubles: true para reconciliar las asignaturas existentes por identificador externo, código o nombre. Es el punto de acceso de un push nocturno de asignaturas.

Existe también un punto de acceso especial, únicamente sobrescribible, os_external_classes_get: Omniscol no entrega ninguna implementación por defecto, pero cuando un socio o un proveedor lo apunta hacia su propio servicio (vía Personalización de API), la pantalla de creación de clase se rellena previamente desde esta lista cerrada de clases en lugar del formulario manual. Sin sobrescritura, simplemente no hace nada.

Para un software SIS / ERP (Aurion, Auriga…), prefiera el conector dedicado a estos puntos de acceso en bruto — véase Sincronización con sistemas externos.