API tiết học — lấy tiết học cho bất kỳ ngày nào

API tiết học: GET /api/schedules/lessons/{datesrange} là điểm truy cập vạn năng để lấy về những tiết học đã có ngày thực tế trong thời khóa biểu của bạn — bất kỳ ngày nào hoặc tập hợp ngày nào, lọc theo đúng những thực thể bạn cần, kèm hoặc không kèm các cấu trúc nền bên dưới, vắng mặt và thay thế, giờ đồng hồ hay chỉ vị trí trên lưới thời gian. Đây là nơi phần lớn tích hợp bắt đầu.

Khi một hệ thống bên ngoài Omniscol cần biết điều gì đang diễn ra, và vào lúc nào, đây là điểm truy cập cần gọi:

GET /api/schedules/lessons/{datesrange}

Nó trả về các tiết học đã có ngày trong thời khóa biểu của bạn — mỗi tiết học đặt đúng vào ngày thực tế của nó — cho những ngày và những thực thể mà bạn yêu cầu. Gần như mọi tích hợp (một intranet, một ETL, một công cụ của đối tác) đều bắt đầu từ đây. Trang này điểm qua các tham số biến nó thành một điểm truy cập duy nhất phục vụ rất nhiều nhu cầu.

Tiết học so với cấu trúc

Hai điểm truy cập, hai vai trò:

• GET /api/schedules/lessons/{datesrange} — các tiết học: mỗi tiết học đặt trên một ngày thực tế, kèm môn học, giáo viên, phòng học, nhóm và thời lượng. Đây là dữ liệu cần đọc để biết ai ở đâu và vào lúc nào.
• GET /api/schedules/ — các cấu trúc: chính những thời khóa biểu đã công bố (lớp, môn học, cơ sở, lưới thời gian). Đọc điểm truy cập này khi bạn cần mô hình nền bên dưới thay vì các tiết học đã có ngày.

Bạn cũng có thể gộp các cấu trúc vào ngay lệnh gọi tiết học bằng with_timetables=true (xem bên dưới): khi đó một lệnh gọi duy nhất trả về cả hai.

Chọn ngày

{datesrange} viết theo dạng YYYYMMDD và được thiết kế để linh hoạt:

Chính dạng rời rạc (ngăn cách bằng dấu phẩy) khiến một câu hỏi kiểu “ba thứ Hai này” chỉ tốn đúng một lệnh gọi.

Nhắm đúng dữ liệu bạn cần

Tham số filter thu hẹp truy vấn về đúng những thực thể đáng quan tâm — vẫn là cú pháp lọc của các điểm truy cập về thời gian rảnh (Truy vấn nâng cao):

• một danh sách mã định danh đơn giản — {"classes":["10a1","10a2"]},
• một ký tự đại diện — {"teachers":"*"},
• một phép so khớp trường đơn giản — {"classrooms":[{"site":"co-so-1"}]},
• hoặc một $where có cấu trúc — {"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}.

Kết quả được nhóm theo loại bộ lọc, rồi theo mã định danh thực thể — ví dụ schedules.classes.10a1.lessons[], schedules.teachers.gv-mai.lessons[].

Cùng mảng đó vẫn còn được trả về dưới tên cũ courses[] trong một giai đoạn chuyển tiếp: hãy viết tích hợp của bạn dựa trên lessons[].

Hai tham số khác khoanh vùng phạm vi trích xuất, và một tham số cuối đặt trần cho nó:

• timetables_restrict / timetables_exclude — giới hạn hoặc loại trừ các mã định danh thời khóa biểu (chuỗi, CSV hoặc mảng).
• limit — đặt trần số tiết học trả về cho mỗi bộ lọc.

Một tiết học trông như thế nào

Mỗi phần tử của lessons[] là một tiết học đã được xếp lịch:

{
  "position": { "day": "2026-10-05", "period": 0, "start": "8:15", "end": "9:10" },
  "duration": 2,
  "subject": "toan",
  "teachers": ["gv-mai"],
  "classroom": "co-so-1:B12",
  "class": "10a1",
  "schedid": "3"
}

• position.day là ngày diễn ra tiết học.
• position.period là chỉ số của tiết học trên lưới thời gian của thời khóa biểu — chỉ có với những tiết học đặt trên lưới. Một tiết học ngoài khung giờ (có start/end riêng, nằm ngoài các khung giờ thường lệ) mang start/end thay cho period.
• position.start / position.end (giờ đồng hồ) luôn đi kèm một tiết học ngoài khung giờ, và được bổ sung cho các tiết học trên lưới khi bạn truyền with_hours=true (giờ đã tính sẵn). Hãy bật tham số này khi hệ thống đích của bạn cần giờ đồng hồ thay vì chỉ số trên lưới.

Vắng mặt, hủy tiết học và thay thế

Theo mặc định, điểm truy cập này hợp nhất các vắng mặt: giáo viên vắng mặt bị gỡ khỏi tiết học, và một tiết học không còn giáo viên nào được xem là đã hủy nên bị loại ra. Một số tham số thay đổi cách xử lý đó:

• without_absences — bỏ qua hoàn toàn các vắng mặt; trả về đúng thời khóa biểu đã lập, chưa qua xử lý.
• with_absences — trả kèm các vắng mặt thô của giai đoạn đó bên cạnh các tiết học.
• with_cancelcourses — giữ lại các tiết học đã hủy (toàn bộ giáo viên đều vắng) thay vì loại chúng ra.
• with_studentcancelcourses — chỉ giữ những tiết học bị hủy vì học sinh vắng mặt.
• with_removedcourses — trả về các tiết học đã bị gỡ bỏ (không dùng chung với with_cancelcourses).
• without_teacher_consolidation — giữ giáo viên vắng mặt trong danh sách teachers của từng tiết học thay vì gỡ họ ra.
• without_holidays — không chèn ngày nghỉ lễ vào khoảng thời gian truy vấn.

Theo mặc định, khi một giáo viên thay thế đã được chỉ định cho một vắng mặt, người này thay thẳng giáo viên vắng mặt trong danh sách teachers của tiết học — việc thay thế diễn ra liền mạch, không thêm trường nào. Nếu bạn truyền with_cancelcourses hoặc without_teacher_consolidation, tiết học sẽ mang thêm một khối substitutes (mã định danh của giáo viên thay thế, lý do vắng mặt và chính vắng mặt đã dẫn tới việc thay thế), để bạn thấy ai được thay và vì sao ngay trong cùng một kết quả trả về.

Cấu trúc và danh bạ

Đính kèm dữ liệu tham chiếu hữu ích, ngay trong cùng một lệnh gọi:

• with_timetables=true — cấu trúc thô của những thời khóa biểu đã dùng để tính ra các tiết học (lớp, môn học, lưới thời gian, theo mã định danh). Bật khi bạn cần phân giải mã định danh; để tắt nếu muốn kết quả gọn nhẹ.
• with_entities=true — tên và mã ở dạng gọn nhẹ (kèm các trường họ tên đối với người) của những thực thể xuất hiện trong kết quả.
• with_teachers / with_all_teachers — những giáo viên có mặt trên các tiết học, hoặc toàn bộ giáo viên của thời khóa biểu và của danh bạ.
• with_students — học sinh, kèm phân công của họ theo từng ngày.
• with_events=true — các sự kiện ngoài khung giờ (buổi họp đánh giá kết quả của lớp, họp phụ huynh…) trong cùng khoảng thời gian.

Một lượt trích xuất ETL ban đêm

Lấy về một tuần tiết học cho toàn bộ các lớp, kèm giờ đồng hồ, rồi nạp vào hệ thống thông tin của bạn:

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

Phản hồi nhóm các tiết học dưới schedules.classes.<id>.lessons[]. Các vắng mặt đã được hợp nhất sẵn: những gì bạn nạp vào phản ánh đúng thời khóa biểu thực tế và cập nhật — thêm with_absences=true nếu bạn còn muốn ghi lại lý do của một thay đổi.

Đẩy dữ liệu vào Omniscol

Việc tích hợp cũng chạy theo chiều ngược lại — để giữ Omniscol khớp với một nguồn dữ liệu gốc bên ngoài. Những điểm truy cập sau chỉ tồn tại cho việc đồng bộ bên ngoài đó; bản thân giao diện Omniscol không bao giờ gọi tới chúng:

• POST /api/external/classes (os_external_classes_post) — cập nhật những lớp đã có (tên, cơ sở, khối, phòng học, sĩ số) từ dữ liệu gửi lên được đánh chỉ mục theo mã định danh lớp. Nó cập nhật các lớp đã biết; nó không tạo lớp mới. Đặt một trường thành null để xóa trường đó (trừ tên lớp — một lớp luôn giữ tên của mình).
• POST /api/external/teachers (os_external_teachers_post) — thêm mới hoặc cập nhật giáo viên theo mã định danh, đồng thời trong các thời khóa biểu và trong danh bạ (tạo người dùng với vai trò giáo viên và một tên đăng nhập được sinh tự động khi cần). Các biến thể DELETE gỡ một lớp hoặc một giáo viên.
• POST /api/admin/subjects/custom (os_admin_subjects-custom_post) — nạp một danh mục môn học tùy chỉnh. Phần thân là { "subjects": [ … ], "replace": false, "nodoubles": true }: mặc định là bổ sung dần, replace: true để làm mới toàn bộ, nodoubles: true để đối chiếu với những môn học đã có theo mã định danh bên ngoài, theo mã hoặc theo tên. Đây chính là điểm truy cập cho một lượt đẩy môn học hằng đêm.

Còn có một điểm truy cập đặc biệt, chỉ tồn tại để được ghi đè, os_external_classes_get: Omniscol không cung cấp bản cài đặt mặc định nào cho nó, nhưng khi một đối tác hoặc một nhà cung cấp trỏ nó sang dịch vụ riêng của họ (qua Tùy chỉnh API), màn hình tạo lớp sẽ tự điền sẵn từ danh sách lớp cố định đó thay vì dùng biểu mẫu nhập tay. Nếu không được ghi đè, nó đơn giản là không làm gì cả.

Với một phần mềm SIS / ERP (Aurion, Auriga…), hãy ưu tiên bộ kết nối chuyên dụng thay vì các điểm truy cập thô này — xem Đồng bộ hóa với các hệ thống bên ngoài.