Consultas avanzadas — filtrar, proyectar y paginar la API

Las tres superficies de un vistazo

Los tres figuran en la referencia de API interactiva (la página /developers), bajo la sección Search, y exigen una autenticación — véase API de Omniscol.

El filtro where (al estilo Mango / MongoDB)

/api/search/entity y /api/search/query aceptan ambos una cláusula where: un filtro estructurado con operadores al estilo MongoDB. Un campo corresponde bien a un valor directo (igualdad implícita), bien a un objeto de operadores; varios operadores sobre el mismo campo se combinan mediante un Y implícito. Los nombres de campo aceptan la notación con puntos para alcanzar un contexto padre (por ejemplo sites.name).

Algunos ejemplos:

{ "capacity": { "$gte": 20, "$lte": 50 } }
{ "level": { "$in": ["L1", "L2", "L3"] } }
{ "name": { "$regex": "^lab" } }
{ "city": { "$like": "ivry sur seine" } }
{ "$or": [ { "capacity": { "$gte": 50 } }, { "specialisation": "chemistry" } ] }

Proyección, orden y paginación

Sobre /api/search/query, cuatro palancas más mantienen la respuesta compacta y ordenada — lo que importa para un panel de control, y más aún para un agente de IA facturado por token:

• project — la lista de campos que conservar (notación con puntos autorizada). Todo lo demás se descarta.
• sort — un campo, asc o desc. El pseudocampo _count.<campo> ordena según la longitud de un campo array.
• limit y offset — paginan los resultados.

La respuesta devuelve también un bloque meta: cuántos elementos existían antes del filtrado, cuántos han pasado el filtro, y cuántos se han devuelto.

Un ejemplo completo

Encontrar las aulas de al menos 30 plazas, conservar solo su nombre y su capacidad, de la más grande a la más pequeña, y tomar las 20 primeras:

curl -X POST "https://su-escuela.omniscol.com/api/search/query" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "call": "os_dashboard_classrooms_get",
        "where": { "capacity": { "$gte": 30 } },
        "project": ["name", "capacity"],
        "sort": { "capacity": "desc" },
        "limit": 20
      }'

call es el nombre interno del punto de acceso de lectura que ejecutar (tal como se muestra en la página /developers), params lleva los parámetros propios de ese punto de acceso, y extract_path designa si es necesario el array que filtrar dentro del resultado — omitido aquí, se detecta automáticamente.

Encontrar un aula o un profesor disponible

La integración más habitual — alimentar una intranet, una herramienta de reservas o un ETL — es «¿quién o qué está libre en tal momento?». Los puntos de acceso availability responden a ello directamente: devuelven, por entidad, únicamente las franjas libres en las fechas solicitadas, teniendo ya en cuenta las sesiones, las ausencias y los deseos obligatorios.

La disponibilidad se solicita de dos maneras:

• Acotada — GET /api/schedules/availability/{datesrange}/{entity} (si es necesario /{entityId}) para un tipo de entidad — teachers, classrooms, groups, resources…
• Filtro explícito — GET /api/schedules/availability/{datesrange} con un filter, donde se restringe el conjunto con el mismo $where visto antes.

{datesrange} se escribe en YYYYMMDD, y segmentos separados por comas solicitan fechas dispersas — perfecto para «dos lunes concretos»: 20261005,20261012. Cada franja devuelta lleva day, start, end y time (en minutos): «al menos 3 horas» se convierte por tanto en una prueba time >= 180 por su parte.

Un profesor libre en una franja concreta

«¿Qué profesores están libres el lunes 5 de octubre?» — una sola llamada acotada:

curl -G "https://su-escuela.omniscol.com/api/schedules/availability/20261005/teachers" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode "with_entities=true"

Las franjas libres vuelven agrupadas por naturaleza, y luego por profesor — por ejemplo { "availability": { "teachers": { "t.dupont": [ { "day": "2026-10-05", "start": "14:00", "end": "17:00", "time": 180 } ] } } } — y su herramienta retiene la que cubre la franja deseada.

Aulas de cierto tamaño, libres en dos lunes

Combine un filtro de entidad y la disponibilidad en una sola llamada, con un subconjunto útil de la sintaxis — solo $where sobre la capacidad:

curl -G "https://su-escuela.omniscol.com/api/schedules/availability/20261005,20261012" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode 'filter={"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}' \
  --data-urlencode "with_entities=true"

Omniscol devuelve las franjas libres, en los dos lunes, de cada aula de al menos 30 plazas. Su ETL retiene después las aulas que tengan una ventana de 3 horas (time >= 180) en cada una de las fechas — la composición sobre varios días queda de su parte, lo que mantiene la regla explícita y verificable.

El filter acepta, por tipo de entidad, una simple lista de identificadores ({"classrooms":["A101","B204"]}), un comodín ({"teachers":"*"}), una correspondencia de campo simple ({"teachers":[{"email":"…"}]}) o el $where estructurado mostrado aquí.

Elegir la superficie adecuada

• «¿Dónde aparece esta palabra?» → POST /api/search.
• «¿A qué entidad corresponde este nombre?» → POST /api/search/entity.
• «Dame las aulas de más de 30 plazas, ordenadas, primera página» → POST /api/search/query.
• «¿Quién o qué está libre en esta franja?» → GET /api/schedules/availability/….

Para un agente de IA

Estas superficies existen en gran parte para los agentes de IA. La búsqueda de texto completo y la resolución de entidad transforman la formulación de un usuario («profesor Jean Dupont», «clase 6A») en identificadores precisos; el orquestador de consultas responde después a una pregunta filtrada en una sola llamada y solo devuelve los campos solicitados — en lugar de varias llamadas y una respuesta sobredimensionada. Cuando conecta un agente vía MCP — conectar un agente de IA externo, estas herramientas forman parte de lo que puede utilizar.

Enchufarlo a una intranet, un ETL o una herramienta de socio

Estas mismas superficies de lectura son lo que una herramienta de tercero consume a diario. Formas habituales:

• Un tirón hacia una intranet o un panel de control — su página llama a los puntos de acceso de lectura (disponibilidad, el punto de acceso de las sesiones, los tableros de control) con un token de API restringido, y muestra el resultado. Nada que instalar del lado de Omniscol.
• Un ETL nocturno — una tarea planificada recupera lo que necesita (las sesiones sobre una ventana de fechas, las horas de un profesor, la ocupación de las aulas) y lo carga en su sistema de información. search/query mantiene cada tirón filtrado, proyectado y paginado, para una respuesta compacta.
• Un empuje desde su sistema — el sentido inverso, para mantener Omniscol alineado con su fuente de verdad: una tarea nocturna puede actualizar clases y profesores (POST /api/external/classes, POST /api/external/teachers) o cargar un catálogo de asignaturas personalizadas (POST /api/admin/subjects/custom) desde su base.
• Un software SIS / ERP — para Aurion, Auriga y compañía, el conector dedicado es la herramienta adecuada — véase Sincronización con sistemas externos.
• Guiado por eventos — para ser notificado de un cambio en lugar de interrogar en bucle, registre un hook — véase Personalización de API.

Mantenga cada integración restringida: un token limitado a los puntos de acceso realmente útiles, renovado con regularidad, y de solo lectura allí donde solo lee. Véase API de Omniscol.