课时API——获取任意日期的课时

课时API：GET /api/schedules/lessons/{datesrange} 是一个万能接口，用于获取您课表中已落到真实日期的课时——可指定任意日期或日期集合，按所需实体筛选，并可选择是否附带底层结构、缺勤和代课、具体时间或仅时段信息。它是大多数集成的起点。

当Omniscol之外的系统需要知道什么时间发生什么时，就调用这个接口：

GET /api/schedules/lessons/{datesrange}

它会针对所请求的日期和实体，返回您课表中的带日期的课时—— 每个课时都落在其真实日期上。几乎所有集成（内网、ETL、合作方工具） 都从这里开始。本页介绍使这个接口能满足多种用途的各项参数。

课时与结构

两个接口，两种职责：

• GET /api/schedules/lessons/{datesrange}——课时： 每个落在真实日期上的课时，包含其科目、教师、教室、小组和时长。 想知道谁在何时何地，就读取它。
• GET /api/schedules/——结构：已发布的课表本身 （班级、科目、校区、时间网格）。需要底层模型而非带日期的课时时，读取它。

也可以通过 with_timetables=true（见下文）把结构并入课时请求： 一次请求即可同时返回两者。

选择日期

{datesrange} 使用 YYYYMMDD 格式，写法刻意设计得很灵活：

零散形式（用逗号分隔）使“这三个周一”这样的问题只需一次调用即可解决。

精确指定所需内容

filter 将请求限制在所需的实体上——其语法与可用时间接口 （高级查询）相同：

• 简单的标识列表——{"classes":["3a","3b"]}，
• 通配符——{"teachers":"*"}，
• 简单的字段匹配——{"classrooms":[{"site":"nord"}]}，
• 或结构化的 $where——{"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}。

结果先按筛选类型分组，再按实体标识分组——例如 schedules.classes.3a.lessons[]、schedules.teachers.j-doe.lessons[]。

另有两个参数用于限定提取范围，还有一个用于设置上限：

• timetables_restrict / timetables_exclude——限定或排除某些课表标识 （字符串、CSV或数组）。
• limit——限制每个筛选条件返回的课时数量上限。

课时的样子

lessons[] 中的每一项都是一个已安排的课时：

{
  "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 是课时的日期。
• position.period 是课时在课表时间网格上的序号——安排在网格上的课时才有。 网格外的课时（自带明确的 start/end，不在常规时段内） 则带有 start/end，没有 period。
• position.start / position.end（时间）始终出现在网格外的课时上； 当您传入 with_hours=true（预先计算的时间）时，网格内的课时也会带上。 当目标系统需要的是时钟时间而非网格序号时，请启用该参数。

缺勤、取消和代课

默认情况下，接口会合并缺勤：缺勤的教师会从课时中移除， 没有剩余教师的课时被视为已取消并被排除。以下参数可改变这一行为：

• without_absences——完全忽略缺勤；返回原始的计划网格。
• with_absences——在课时旁附上该时间段的原始缺勤记录。
• with_cancellessons——保留已取消的课时（所有教师都缺勤），而不是排除它们。
• with_studentcancellessons——只保留因学生缺勤而取消的课时。
• with_removedlessons——返回已移除的课时（与 with_cancellessons 互斥）。
• without_teacher_consolidation——在每个课时的 teachers 列表中保留缺勤的教师，而不是移除。
• without_holidays——不在该范围内插入假期。

默认情况下，当某次缺勤已指定代课教师时，他会直接替换课时 teachers 列表中缺勤的教师—— 代课是透明的，没有额外字段。传入 with_cancellessons 或 without_teacher_consolidation 后，课时还会带有一个 substitutes 块（代课教师的标识、缺勤原因以及引发代课的缺勤记录）， 让您在同一份数据中看到谁被替换以及原因。

结构与名录

可在同一次调用中附带所需的参考数据：

• with_timetables=true——计算课时所用的课表原始结构 （班级、科目、时间网格，按标识组织）。需要解析标识时启用； 想要精简的响应时请保持关闭。
• with_entities=true——结果中各实体的精简名称/代码（以及人员的姓名字段）。
• with_teachers / with_all_teachers——课时中用到的教师， 或课表和名录中的所有教师。
• with_students——学生及其按日期的分配。
• with_events=true——同一时间范围内网格外的事件（班级评议会、家长会等）。

夜间ETL拉取

获取所有班级一周的课时（含具体时间），并加载到您的信息系统：

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

响应会把课时归入 schedules.classes.<id>.lessons[]。 缺勤已合并：您加载的内容反映的是实时、最新的课表—— 如果还想记录变更原因，请加上 with_absences=true。

推送到Omniscol

集成也可以反向进行——让Omniscol与外部权威数据源保持一致。

对于学生信息系统或ERP软件（Aurion、Auriga等），请优先使用专用连接器， 而不是下面的原始接口——参见与外部系统同步。

班级与教师

这些接口仅用于与外部系统同步；Omniscol界面自己从不调用它们：

• POST /api/external/classes（os_external_classes_post）—— 根据按班级标识索引的数据，更新已有班级 （名称、校区、年级、教室、人数）。它只更新已知班级，不会创建新班级。 将某个字段设为 null 即可清除它（班级名称除外——班级必须保留名称）。
• POST /api/external/teachers（os_external_teachers_post）—— 按标识插入或更新教师，同时作用于课表和名录 （必要时会创建具有教师角色的用户，并自动生成登录名）。 DELETE 变体用于移除班级或教师。

还有一个特殊接口 os_external_classes_get，只能被覆盖： Omniscol不提供默认实现，但当合作方或供应商通过 API自定义将其指向自己的服务时， 创建班级的界面会根据这份封闭的班级列表预填，而不再使用手动表单。 没有覆盖时，它什么都不做。

自定义科目

POST /api/admin/subjects/custom（os_admin_subjects-custom_post） 可加载一份自定义科目目录，或只创建一个科目。界面也会使用它。 目录请求体为 { "subjects": [ … ], "replace": false, "duplicates_reuse": true }： 默认为增量更新，replace: true 表示完全刷新， duplicates_reuse: true（默认值）表示按外部标识、代码或名称与已有科目匹配。 这是每晚推送科目时使用的接口。