Logo HanoiStudyTài liệu Trục LMS Hà Nội
Tìm kiếm tài liệu...

Hướng dẫn tích hợp API Đồng bộ Lịch báo giảng

Hướng dẫn tích hợp PartnerApi để đồng bộ dữ liệu lịch báo giảng lên Trục LMS.

1. Mục tiêu

Tài liệu này hướng dẫn đơn vị tích hợp giao diện lập trình ứng dụng PartnerApi để đồng bộ dữ liệu lịch báo giảng.

Tài liệu tập trung vào:

  • Cách gọi bằng curl
  • Ý nghĩa và ràng buộc của toàn bộ dữ liệu đầu vào
  • Cách đọc dữ liệu phản hồi theo từng bản ghi

2. Thông tin kết nối

2.1. Địa chỉ dịch vụ

  • Địa chỉ gọi dịch vụ: https://lmsbpartnerapi.vstudy.edu.vn/
  • Tài liệu kiểm tra nhanh: https://lmsbpartnerapi.vstudy.edu.vn/swagger/index.html

2.2. Header bắt buộc

Tất cả giao diện lập trình ứng dụng đồng bộ yêu cầu:

  • X-Api-Key: <api-key-do-don-vi-duoc-cap>
  • Content-Type: application/json

PartnerId được lấy từ X-Api-Key (không truyền trong dữ liệu thân yêu cầu).

Để lấy X-Api-Key, vui lòng liên hệ đơn vị QIG.

3. Danh sách endpoint lịch báo giảng

  • POST /api/lms-base/teaching-plans: Tạo mới hoặc cập nhật danh sách lịch báo giảng
  • DELETE /api/lms-base/teaching-plans: Xóa danh sách lịch báo giảng theo SourceId

4. Tạo mới hoặc cập nhật lịch báo giảng

4.1. cURL tạo mới hoặc cập nhật

curl --location --request POST "https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/teaching-plans" \
  --header "X-Api-Key: <YOUR_API_KEY>" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "sourceId": "TP-20260411-0001",
      "doetCode": "01",
      "divisionCode": "00004",
      "schoolCode": "01000865",
      "academicYearCode": 2025,
      "gradeLevelCode": "04",
      "semesterCode": "2",
      "teacherPinCode": "001056008234",
      "weekNumber": 15,
      "session": "SANG",
      "dayOfWeek": 2,
      "teachingStartTime": "2026-04-06T00:00:00Z",
      "teachingEndTime": "2026-04-06T00:45:00Z",
      "period": 1,
      "curriculumPeriod": "Tiet phan phoi chuong trinh 01",
      "subjectCode": "0201",
      "classCode": "4A08",
      "lessonName": "Phan so va phep cong",
      "teachingType": "B",
      "teachingMethod": "OFFLINE",
      "room": "P.201",
      "note": "Dong bo dot 1"
    }
  ]'
bash

4.2. Ý nghĩa toàn bộ dữ liệu đầu vào (UpsertTeachingPlanRequest)

| Trường | Kiểu | Bắt buộc | Ý nghĩa | Ràng buộc chính | |---|---|---|---|---| | sourceId | string | Có | Mã bản ghi từ hệ thống đối tác | Khóa đồng bộ với PartnerId | | doetCode | string | Có | Mã Sở Giáo dục và Đào tạo | Không rỗng, phải tồn tại trong LmsMaster | | divisionCode | string? | Không | Mã phòng hoặc xã hoặc phường | Nếu có giá trị thì phải tồn tại theo ngữ cảnh Sở | | schoolCode | string | Có | Mã trường | Không rỗng, phải tồn tại đúng ngữ cảnh Sở và đơn vị quản lý | | branchCode | string? | Không | Mã phân hiệu (cơ sở) của lớp | Bắt buộc khi classCode trùng giữa nhiều phân hiệu của cùng schoolCode; lớp thuộc cơ sở chính thì gửi bằng schoolCode. Xem mục 4.3 | | academicYearCode | int | Có | Năm học | > 0 | | gradeLevelCode | string | Có | Mã khối hoặc cấp học | Chỉ nhận: 01: Mầm non, 02: Tiểu học, 03: THCS, 04: THPT, 05:GDTX | | semesterCode | string | Có | Học kỳ | Chỉ nhận: 1 hoặc 2 | | teacherPinCode | string | Có | Căn cước công dân của giáo viên | Phải tồn tại trong cơ sở dữ liệu | | weekNumber | int | Có | Tuần học trong học kỳ | > 0 | | session | string | Có | Buổi học | Chỉ nhận SANG hoặc CHIEU (không phân biệt chữ hoa, chữ thường) | | dayOfWeek | byte | Có | Thứ trong tuần | Từ 2..8 (8 là Chủ nhật) | | teachingStartTime | DateTime | Có | Giờ bắt đầu tiết học | Định dạng ISO 8601, múi giờ UTC | | teachingEndTime | DateTime? | Không | Giờ kết thúc tiết học | Định dạng ISO 8601, múi giờ UTC | | period | int | Có | Số tiết | > 0 | | curriculumPeriod | string? | Không | Tiết theo phân phối chương trình | Chuỗi tự do | | subjectCode | string | Có | Mã môn học | Phải tồn tại trong danh mục môn học chuẩn | | classCode | string | Có | Mã lớp | Phải tồn tại trong schoolCode + academicYearCode, và thuộc branchCode nếu có gửi | | lessonName | string? | Không | Tên bài dạy | Chuỗi tự do | | teachingType | string? | Không | Kiểu giảng dạy | Chỉ nhận: B, LT, TH, OT, KT, TB, THI, LEN_LOP, DAY_BU, DAY_THAY, LAP_GIO, NGHI_LE, NGHI_DAY; mặc định B nếu không gửi | | teachingMethod | string? | Không | Phương thức dạy học | Ví dụ: ONLINE, OFFLINE | | room | string? | Không | Phòng học | Chuỗi tự do | | note | string? | Không | Ghi chú | Chuỗi tự do |

Ghi chú:

  • Ý nghĩa các giá trị của teachingType:
  • B: Bài mới, giảng dạy kiến thức mới.
  • LT: Luyện tập, củng cố kiến thức thông qua bài tập.
  • TH: Thực hành hoặc thí nghiệm, vận dụng lý thuyết vào thực tiễn.
  • OT: Ôn tập, hệ thống lại kiến thức sau một chương hoặc chuyên đề.
  • KT: Kiểm tra, các bài kiểm tra thường xuyên hoặc định kỳ.
  • TB: Trả bài, chữa bài kiểm tra cho học sinh.
  • THI: Thi, tham gia kỳ thi.
  • LEN_LOP: Lên lớp.
  • DAY_BU: Dạy bù.
  • DAY_THAY: Dạy thay.
  • LAP_GIO: Lấp giờ.
  • NGHI_LE: Nghỉ lễ.
  • NGHI_DAY: Nghỉ dạy.
  • Hệ thống tự lấy TeacherName, ClassName, SubjectName từ dữ liệu tham chiếu.
  • Hệ thống tạo mới hoặc cập nhật theo PartnerId + sourceId: khi sourceId đã tồn tại thì các trường nghiệp vụ khác vẫn được cập nhật.
  • Hệ thống xử lý theo danh sách: bản ghi lỗi không chặn các bản ghi hợp lệ khác.

4.3. Đồng bộ lớp thuộc phân hiệu (branchCode)

Một trường có thể có cơ sở chính và nhiều phân hiệu, các phân hiệu dùng chung schoolCode và có thể có lớp trùng classCode. Trường branchCode giúp hệ thống xác định đúng lớp:

  • Nếu classCode là duy nhất trong schoolCode + academicYearCode: có thể bỏ trống branchCode, hệ thống tự xác định phân hiệu theo lớp.
  • Nếu classCode trùng giữa nhiều phân hiệu: bắt buộc gửi branchCode, nếu không bản ghi bị từ chối.
  • Lớp thuộc cơ sở chính: gửi branchCode bằng chính schoolCode.
  • Lớp thuộc phân hiệu: gửi branchCode bằng mã phân hiệu trong danh mục trường của Cơ sở dữ liệu ngành.
  • branchCode không phân biệt chữ hoa, chữ thường; nếu không khớp với phân hiệu của lớp thì bản ghi bị từ chối.
  • Hệ thống lưu mã phân hiệu theo lớp đã xác định được, dùng để phân quyền xem dữ liệu theo phân hiệu.

Ví dụ phần tử gửi cho lớp thuộc phân hiệu:

{
  "sourceId": "TP-20260411-0002",
  "doetCode": "01",
  "schoolCode": "01000865",
  "branchCode": "<MA_PHAN_HIEU>",
  "classCode": "4A08",
  "...": "các trường khác như ví dụ ở mục 4.1"
}
json

4.4. Mô hình dữ liệu phản hồi khi tạo mới hoặc cập nhật

Mô hình phản hồi cấp ngoài:

{
  "data": [
    {
      "id": "string-ulid-hoac-null",
      "sourceId": "string",
      "isCreated": true,
      "isSuccess": true,
      "message": "string-hoac-null",
      "processedAt": "2026-04-08T07:30:00.0000000Z"
    }
  ],
  "message": "string",
  "success": true
}
json

Mô hình chi tiết từng phần tử trong data (TeachingPlanSyncResponse):

  • id: định danh kiểu Ulid, có thể null khi bản ghi lỗi
  • sourceId: mã bản ghi từ hệ thống nguồn
  • isCreated:
  • true: tạo mới
  • false: cập nhật
  • null: bản ghi lỗi
  • isSuccess: kết quả xử lý từng bản ghi
  • message: thông điệp chi tiết từng bản ghi
  • processedAt: thời điểm xử lý theo múi giờ UTC

Ví dụ phản hồi:

{
  "data": [
    {
      "id": "01KNXQVNZGGSJXBCX9CY49W830",
      "sourceId": "TP-20260411-0001",
      "isCreated": true,
      "isSuccess": true,
      "message": "Đồng bộ thành công.",
      "processedAt": "2026-04-11T07:42:13.2944263Z"
    }
  ],
  "message": "Đồng bộ 1 lịch báo giảng: thành công 1, lỗi 0.",
  "success": true
}
json

5. Xóa lịch báo giảng

5.1. cURL xóa

curl --location --request DELETE "https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/teaching-plans" \
  --header "X-Api-Key: <YOUR_API_KEY>" \
  --header "Content-Type: application/json" \
  --data-raw '[
    "TP-20260411-0001",
    "TP-20260411-0002"
  ]'
bash

Dữ liệu đầu vào của giao diện lập trình ứng dụng xóa:

  • Dữ liệu thân yêu cầu là mảng string[]
  • Mỗi phần tử là SourceId cần xóa
  • Hệ thống xóa theo khóa PartnerId + SourceId

5.2. Mô hình dữ liệu phản hồi khi xóa

Mô hình phản hồi cấp ngoài:

{
  "data": [
    {
      "sourceId": "string",
      "deleted": true,
      "processedAt": "2026-04-08T07:30:00.0000000Z"
    }
  ],
  "message": "string",
  "success": true
}
json

Mô hình chi tiết từng phần tử trong data (TeachingPlanDeleteResponse):

  • sourceId: mã bản ghi từ hệ thống nguồn
  • deleted:
  • true: đã xóa
  • false: không tìm thấy để xóa
  • processedAt: thời điểm xử lý theo múi giờ UTC

Ví dụ phản hồi:

{
  "data": [
    {
      "sourceId": "TP-20260411-0001",
      "deleted": true,
      "processedAt": "2026-04-11T07:42:30.1200000Z"
    }
  ],
  "message": "Xử lý xóa 1 lịch báo giảng, xóa thành công 1 bản ghi.",
  "success": true
}
json

6. Mã trạng thái thường gặp

  • 200 OK: yêu cầu được xử lý (có thể có bản ghi thành công và bản ghi lỗi trong cùng dữ liệu phản hồi)
  • 400 Bad Request: dữ liệu thân yêu cầu không hợp lệ ở mức yêu cầu (ví dụ danh sách rỗng)
  • 401 Unauthorized: thiếu hoặc sai X-Api-Key
  • 409 Conflict: xung đột dữ liệu

Ví dụ thông điệp lỗi theo từng bản ghi:

  • Bản ghi lịch báo giảng tại vị trí 3 không hợp lệ: SemesterCode chỉ chấp nhận giá trị 1 hoặc 2.
  • Bản ghi tại vị trí 5 không hợp lệ: SubjectCode '9999' không tồn tại hoặc không hoạt động.
  • Bản ghi tại vị trí 2 không hợp lệ: ClassCode '4A08' thuộc nhiều phân hiệu; cần gửi BranchCode.
  • Bản ghi tại vị trí 4 không hợp lệ: ClassCode '4A08' không tồn tại trong SchoolCode/BranchCode/Năm học tương ứng.

7. Khuyến nghị tích hợp

  • Luôn giữ sourceId ổn định cho cùng một bản ghi nghiệp vụ để bảo đảm cập nhật đúng bản ghi.
  • Chuẩn hóa dữ liệu mã trước khi gửi (cắt khoảng trắng ở đầu và cuối).
  • Gửi thời gian theo múi giờ UTC, định dạng ISO 8601 (yyyy-MM-ddTHH:mm:ssZ).
  • Đồng bộ theo lô vừa phải (ví dụ 100 đến 500 bản ghi mỗi lần) để dễ theo dõi lỗi.
  • Luôn đọc data[].isSuccess và data[].message để xử lý gửi lại theo từng bản ghi lỗi.
  • Với trường có phân hiệu, nên luôn gửi branchCode cho mọi bản ghi để tránh lỗi khi phát sinh lớp trùng mã giữa các phân hiệu.
  • Bản ghi đã đồng bộ trước khi có branchCode nên được gửi lại để hệ thống cập nhật mã phân hiệu.

8. Lịch sử cập nhật

  • 2026-09-27: Bổ sung trường branchCode (mã phân hiệu) cho dữ liệu đầu vào và thông điệp lỗi liên quan.
Tiếp theo
Đồng bộ Thời khóa biểu