A API das aulas — recuperar as aulas para qualquer data

A API das aulas: GET /api/schedules/lessons/{datesrange} é o ponto de acesso faz-tudo para recuperar as aulas realmente datadas dos seus horários — qualquer data ou conjunto de datas, filtrado sobre as entidades desejadas, com ou sem as estruturas subjacentes, as ausências e as substituições, os horários de relógio ou as simples posições de grade. É o ponto de partida da maioria das integrações.

Quando algo fora do Omniscol precisa saber o que acontece, e quando, é este ponto de acesso que se chama:

GET /api/schedules/lessons/{datesrange}

Ele devolve as aulas datadas dos seus horários — cada aula posta na sua data real — para as datas e as entidades solicitadas. Quase toda integração (um intranet, um ETL, uma ferramenta parceira) parte daí. Esta página percorre as alavancas que fazem dele um só ponto de acesso para numerosos usos.

Aulas vs estruturas

Dois pontos de acesso, dois papéis:

• GET /api/schedules/lessons/{datesrange} — as aulas: cada aula posta numa data real, com a sua disciplina, os seus professores, a sua sala, o seu grupo e a sua duração. É o que se lê para saber quem está onde e quando.
• GET /api/schedules/ — as estruturas: os próprios horários publicados (turmas, disciplinas, sites, a grade). A ler quando se precisa do modelo subjacente em vez das aulas datadas.

Também se podem dobrar as estruturas na chamada das aulas com with_timetables=true (veja mais abaixo): uma só requisição devolve então as duas.

Escolher as datas

{datesrange} escreve-se em YYYYMMDD e quer-se voluntariamente flexível:

A forma esparsa (separada por vírgulas) é o que faz de uma pergunta como « estas três segundas-feiras » uma só chamada.

Mirar aquilo de que você precisa

Um filter restringe a requisição às entidades que contam — a mesma gramática de filtro que os pontos de acesso de disponibilidade (Consultas avançadas):

• uma simples lista de identificadores — {"classes":["3a","3b"]},
• um curinga — {"teachers":"*"},
• uma correspondência de campo simples — {"classrooms":[{"site":"nord"}]},
• ou um $where estruturado — {"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}.

O resultado é agrupado por tipo de filtro, depois por identificador de entidade — por exemplo schedules.classes.3a.courses[], schedules.teachers.j-doe.courses[].

Dois outros ajustes enquadram a extração, e um último a limita:

• timetables_restrict / timetables_exclude — limitar ou excluir identificadores de horário (cadeia, CSV ou array).
• limit — limitar o número de aulas devolvidas por filtro.

Como é uma aula

Cada entrada de courses[] é uma aula posta:

{
  "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 é a data da aula.
• position.period é o índice da aula na grade do horário — presente para as aulas postas na grade. Uma aula fora da grade (com os seus próprios start/end explícitos, fora das faixas regulares) leva start/end em vez disso, sem period.
• position.start / position.end (horários de relógio) acompanham sempre uma aula fora da grade, e acrescentam-se às aulas de grade quando você passa with_hours=true (horários pré-calculados). A ativar quando o seu sistema-alvo precisa das horas de relógio em vez do índice de grade.

Ausências, cancelamentos e substituições

Por padrão, o ponto de acesso consolida as ausências: um professor ausente é retirado da aula, e uma aula sem professor restante é considerada cancelada e descartada. Vários indicadores mudam isso:

• without_absences — ignorar completamente as ausências; devolver a grade planejada bruta.
• with_absences — acrescentar as ausências brutas do período ao lado das aulas.
• with_cancelcourses — conservar as aulas canceladas (todos os professores ausentes) em vez de descartá-las.
• with_studentcancelcourses — manter apenas as aulas canceladas pela ausência de um aluno.
• with_removedcourses — devolver as aulas retiradas (exclusivo com with_cancelcourses).
• without_teacher_consolidation — manter os professores ausentes na lista teachers de cada aula em vez de retirá-los.
• without_holidays — não injetar as férias na faixa.

Por padrão, quando um substituto foi designado para uma ausência, ele substitui simplesmente o professor ausente na lista teachers da aula — a substituição é transparente, sem campo suplementar. Passe with_cancelcourses ou without_teacher_consolidation e a aula leva além disso um bloco substitutes (o identificador do substituto, o motivo da ausência e a ausência que a impôs), para ver quem foi substituído e por quê na mesma carga útil.

Estruturas e diretórios

Anexe os dados de referência úteis, na mesma chamada:

• with_timetables=true — as estruturas brutas dos horários que serviram para calcular as aulas (turmas, disciplinas, grade, por identificador). A ativar para resolver os identificadores; a deixar desativado para uma resposta compacta.
• with_entities=true — nome/código leves (e campos de nome de pessoa) das entidades do resultado.
• with_teachers / with_all_teachers — os professores usados nas aulas, ou todos os professores do horário e do diretório.
• with_students — os alunos, com os seus posicionamentos por data.
• with_events=true — os eventos fora da grade (conselhos, reuniões de pais e professores…) sobre a mesma faixa.

Um puxão ETL noturno

Recuperar uma semana de aulas para todas as turmas, com os horários, e carregá-la no seu sistema de informação:

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

A resposta agrupa as aulas sob schedules.classes.<id>.courses[]. As ausências já estão consolidadas: o que você carrega reflete o horário real e atualizado — acrescente with_absences=true se você quiser também registrar a razão de uma mudança.

Injetar para o Omniscol

A integração funciona também no outro sentido — para manter o Omniscol alinhado com uma fonte de verdade externa. Estes pontos de acesso existem unicamente para essa sincronização externa; a interface do Omniscol nunca os chama ela própria:

• POST /api/external/classes (os_external_classes_post) — atualizar turmas existentes (nome, site, nível, sala, efetivo) a partir de uma carga útil indexada por identificador de turma. Ele atualiza as turmas conhecidas; não cria novas. Coloque um campo em null para o apagar (o nome da turma exceptuado — uma turma conserva o seu nome).
• POST /api/external/teachers (os_external_teachers_post) — inserir ou atualizar professores por identificador, tanto nos horários como no diretório (criando o usuário com o papel professor e um login autogerado se necessário). As variantes DELETE retiram uma turma ou um professor.
• POST /api/admin/subjects/custom (os_admin_subjects-custom_post) — carregar um catálogo de disciplinas personalizadas. O corpo é { "subjects": [ … ], "replace": false, "nodoubles": true }: incremental por padrão, replace: true para uma atualização completa, nodoubles: true para reaproximar as disciplinas existentes por identificador externo, código ou nome. É o ponto de acesso de uma injeção noturna de disciplinas.

Existe também um ponto de acesso especial, unicamente substituível, os_external_classes_get: o Omniscol não entrega nenhuma implementação por padrão, mas quando um parceiro ou um fornecedor o aponta para o seu próprio serviço (via Personalização de API), a tela de criação de turma preenche-se previamente a partir desta lista fechada de turmas em vez do formulário manual. Sem substituição, ele simplesmente não faz nada.

Para um pacote de software SIS / ERP (Aurion, Auriga…), prefira o conector dedicado a estes pontos de acesso brutos — veja Sincronização com sistemas externos.