Consultas avançadas — filtrar, projetar e paginar a API

As três superfícies num relance

As três figuram na referência de API interativa (a página /developers), sob a seção Search, e exigem uma autenticação — veja API Omniscol.

O filtro where (ao estilo Mango / MongoDB)

/api/search/entity e /api/search/query aceitam ambos uma cláusula where: um filtro estruturado com operadores ao estilo MongoDB. Um campo corresponde ora a um valor direto (igualdade implícita), ora a um objeto de operadores; vários operadores sobre o mesmo campo combinam-se por um E implícito. Os nomes de campo aceitam a notação com pontos para alcançar um contexto pai (por exemplo sites.name).

Alguns exemplos:

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

Projeção, ordenação e paginação

Sobre /api/search/query, mais quatro alavancas mantêm a resposta compacta e ordenada — o que conta para um painel de controle, e mais ainda para um agente IA faturado por token:

• project — a lista de campos a conservar (notação com pontos autorizada). Todo o resto é descartado.
• sort — um campo, asc ou desc. O pseudocampo _count.<campo> ordena segundo o comprimento de um campo array.
• limit e offset — paginam os resultados.

A resposta devolve também um bloco meta: quantos elementos existiam antes da filtragem, quantos passaram o filtro, e quantos foram devolvidos.

Um exemplo completo

Encontrar as salas de pelo menos 30 lugares, conservar apenas o seu nome e a sua capacidade, da maior para a menor, e tomar as 20 primeiras:

curl -X POST "https://sua-escola.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 é o nome interno do ponto de acesso em leitura a executar (tal como exibido na página /developers), params leva os parâmetros próprios desse ponto de acesso, e extract_path designa se necessário o array a filtrar dentro do resultado — omitido aqui, ele é detectado automaticamente.

Encontrar uma sala ou um professor livre

A integração mais comum — alimentar um intranet, uma ferramenta de reservas ou um ETL — é « quem ou o que está livre em tal momento? ». Os pontos de acesso availability respondem a isso diretamente: devolvem, por entidade, unicamente as faixas horárias livres nas datas solicitadas, tendo já em conta as aulas, as ausências e as disponibilidades obrigatórias.

A disponibilidade solicita-se de duas maneiras:

• Escopada — GET /api/schedules/availability/{datesrange}/{entity} (se necessário /{entityId}) para um tipo de entidade — teachers, classrooms, groups, resources…
• Filtro explícito — GET /api/schedules/availability/{datesrange} com um filter, onde se restringe o conjunto com o mesmo $where visto acima.

{datesrange} escreve-se em YYYYMMDD, e segmentos separados por vírgulas solicitam datas esparsas — perfeito para « duas segundas-feiras precisas »: 20261005,20261012. Cada faixa horária devolvida leva day, start, end e time (em minutos): « pelo menos 3 horas » torna-se, portanto, um teste time >= 180 do seu lado.

Um professor livre numa faixa horária precisa

« Que professores estão livres na segunda-feira 5 de outubro? » — uma só chamada escopada:

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

As faixas horárias livres voltam agrupadas por natureza, depois por professor — por exemplo { "availability": { "teachers": { "t.dupont": [ { "day": "2026-10-05", "start": "14:00", "end": "17:00", "time": 180 } ] } } } — e a sua ferramenta retém aquela que cobre a faixa horária desejada.

Salas de certo tamanho, livres em duas segundas-feiras

Combine um filtro de entidade e a disponibilidade numa só chamada, com um subconjunto útil da sintaxe — apenas $where sobre a capacidade:

curl -G "https://sua-escola.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"

O Omniscol devolve as faixas horárias livres, nas duas segundas-feiras, de cada sala de pelo menos 30 lugares. O seu ETL retém em seguida as salas que tenham uma janela de 3 horas (time >= 180) em cada uma das datas — a composição sobre vários dias fica do seu lado, o que mantém a regra explícita e verificável.

O filter aceita, por tipo de entidade, uma simples lista de identificadores ({"classrooms":["A101","B204"]}), um curinga ({"teachers":"*"}), uma correspondência de campo simples ({"teachers":[{"email":"…"}]}) ou o $where estruturado mostrado aqui.

Escolher a superfície certa

• « Onde aparece esta palavra? » → POST /api/search.
• « A que entidade corresponde este nome? » → POST /api/search/entity.
• « Dê-me as salas de mais de 30 lugares, ordenadas, primeira página » → POST /api/search/query.
• « Quem ou o que está livre nesta faixa horária? » → GET /api/schedules/availability/….

Para um agente IA

Essas superfícies existem em grande parte para os agentes IA. A busca de texto completo e a resolução de entidade transformam a formulação de um usuário (« professor Jean Dupont », « turma 6A ») em identificadores precisos; o orquestrador de consultas responde em seguida a uma pergunta filtrada numa só chamada e devolve apenas os campos solicitados — em vez de várias chamadas e de uma resposta sobredimensionada. Quando você conecta um agente via MCP — conectar um agente IA externo, essas ferramentas fazem parte do que ele pode utilizar.

Ligá-lo a um intranet, um ETL ou uma ferramenta parceira

Essas mesmas superfícies em leitura são o que uma ferramenta terceira consome no dia a dia. Formas comuns:

• Um puxão para um intranet ou um painel de controle — a sua página chama os pontos de acesso em leitura (disponibilidade, o ponto de acesso das aulas, os painéis de controle) com um token de API restrito, e exibe o resultado. Nada a instalar do lado do Omniscol.
• Um ETL noturno — uma tarefa planejada recupera aquilo de que precisa (as aulas sobre uma janela de datas, as horas de um professor, a ocupação das salas) e carrega-o no seu sistema de informação. search/query mantém cada puxão filtrado, projetado e paginado, para uma resposta compacta.
• Uma injeção a partir do seu sistema — o sentido inverso, para manter o Omniscol alinhado com a sua fonte de verdade: uma tarefa noturna pode atualizar turmas e professores (POST /api/external/classes, POST /api/external/teachers) ou carregar um catálogo de disciplinas personalizadas (POST /api/admin/subjects/custom) a partir da sua base.
• Um pacote de software SIS / ERP — para Aurion, Auriga e afins, o conector dedicado é a ferramenta adequada — veja Sincronização com sistemas externos.
• Guiado por eventos — para ser notificado de uma mudança em vez de interrogar em ciclo, registre um hook — veja Personalização de API.

Mantenha cada integração restrita: um token limitado aos pontos de acesso realmente úteis, renovado com regularidade, e apenas em leitura onde ela só lê. Veja API Omniscol.