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

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

Tần suất đồng bộ

• Đồng bộ các bản ghi theo trường
• Vào chủ nhật hàng tuần

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

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

• Môi trường prod: https://partner.vstudy.edu.vn/
• Môi trường kiểm thử: 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://partner.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"
    }
  ]'

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

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.
• Nếu có loại khác vui lòng liên hệ với QIG để chúng tôi bổ sung.
• 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. 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
}

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
}

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

5.1. cURL xóa

curl --location --request DELETE "https://partner.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"
  ]'

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
}

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
}

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.

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.