Hướng dẫn tích hợp API tra cứu chương trình, môn học và đơn vị kiến thức

Tài liệu này hướng dẫn tích hợp các API tra cứu danh mục thuộc KnowledgeUnitsController của QIG.BaseLms.PartnerApi. Bộ API này thường được dùng trước khi gọi API chia sẻ học liệu để lấy đúng curriculumProgramCode, subjectCode, gradeCode và knowledgeUnitCode.

1. Mục tiêu

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

• Danh sách đầy đủ 5 endpoint thuộc KnowledgeUnitsController
• Cách lọc dữ liệu theo curriculumProgramCode, gradeCode, subjectCode
• Ý nghĩa của từng field response
• Luồng gọi khuyến nghị trước khi đồng bộ học liệu

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

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

• Base URL: https://lmsbpartnerapi.vstudy.edu.vn
• Swagger tham khảo nhanh: https://lmsbpartnerapi.vstudy.edu.vn/swagger/index.html

2.2. Xác thực

• Các API trong tài liệu này hiện không bắt buộc gửi X-Api-Key
• Có thể gọi ẩn danh để tra cứu danh mục dùng chung
• Swagger hiện vẫn hiển thị ô Authorize do cấu hình OpenAPI áp dụng chung cho toàn bộ tài liệu; tuy nhiên KnowledgeUnitsController đang được đánh dấu AllowAnonymous

2.3. Format response chung

Tất cả response dùng cùng một cấu trúc:

{
  "success": true,
  "message": "Mô tả kết quả",
  "data": []
}

2.4. Lưu ý về query string

• Các mã tra cứu như curriculumProgramCode, gradeCode, subjectCode được xử lý theo kiểu bỏ khoảng trắng đầu cuối và so sánh không phân biệt hoa thường
• Query parameter của ASP.NET Core được bind không phân biệt hoa thường; ví dụ trong tài liệu dùng gradeCode, subjectCode, curriculumProgramCode
• Có thể không cần truyền các tham số để lấy tất cả bản ghi của Api.

3. Danh sách endpoint

• GET /api/lms-base/publish/knowledge-units/curriculum-programs: tra cứu chương trình
• GET /api/lms-base/publish/knowledge-units/grades: tra cứu danh sách khối
• GET /api/lms-base/publish/knowledge-units/subjects: tra cứu môn học
• GET /api/lms-base/publish/knowledge-units/subject-grades: tra cứu mapping khối và môn học
• GET /api/lms-base/publish/knowledge-units: tra cứu danh sách đơn vị kiến thức dạng phẳng

4. Luồng gọi khuyến nghị

1. Gọi grades để lấy gradeCode chuẩn từ 01 đến 12.
2. Gọi curriculum-programs để lấy mã chương trình đang dùng.
3. Gọi subjects để lấy danh sách môn học theo curriculumProgramCode và hoặc gradeCode.
4. Gọi subject-grades nếu cần kiểm tra lại mapping khối và môn.
5. Gọi knowledge-units để lấy knowledgeUnitCode phù hợp trước khi gửi học liệu.

Nếu tích hợp với API chia sẻ học liệu:

• gradeCode nên lấy trực tiếp từ endpoint grades; nếu hệ thống nguồn đã có mã khối tương thích thì có thể đối soát thêm bằng subject-grades
• curriculumProgramCode lấy từ endpoint curriculum-programs
• subjectCode lấy từ endpoint subjects
• knowledgeUnitCode chính là field code trả về từ endpoint GET /api/lms-base/publish/knowledge-units

5. API chi tiết

5.1. Tra cứu khối

• Method: GET
• Path: /api/lms-base/publish/knowledge-units/grades

Query params:

• Không có

Response data[]:

Ví dụ curl:

curl --location "https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/publish/knowledge-units/grades"

Ví dụ response:

{
  "success": true,
  "message": "Lấy danh sách khối thành công.",
  "data": [
    {
      "code": "01",
      "name": "Khối 1"
    },
    {
      "code": "02",
      "name": "Khối 2"
    },
    {
      "code": "12",
      "name": "Khối 12"
    }
  ]
}

Ghi chú:

• Endpoint trả về danh sách cố định từ 01 đến 12
• Kết quả được sắp xếp tăng dần theo mã khối

5.2. Tra cứu chương trình

• Method: GET
• Path: /api/lms-base/publish/knowledge-units/curriculum-programs

Query params:

Response data[]:

Ví dụ curl:

curl --location "https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/publish/knowledge-units/curriculum-programs?activeOnly=true"

Ví dụ response:

{
  "success": true,
  "message": "Lấy danh sách chương trình thành công.",
  "data": [
    {
      "id": "01JTESTCUR0000000000000001",
      "code": "CUR01",
      "name": "Chương trình GDPT 2018",
      "displayOrder": 1,
      "isActive": true
    }
  ]
}

Ghi chú:

• Kết quả được sắp xếp theo displayOrder tăng dần, sau đó theo code
• Nếu không truyền activeOnly, hệ thống chỉ trả về dữ liệu đang hoạt động

5.3. Tra cứu môn học

• Method: GET
• Path: /api/lms-base/publish/knowledge-units/subjects

Query params:

Response data[]:

Ví dụ curl:

curl --location "https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/publish/knowledge-units/subjects?curriculumProgramCode=CUR01&gradeCode=10&activeOnly=true"

Ví dụ response:

{
  "success": true,
  "message": "Lấy danh sách môn học thành công.",
  "data": [
    {
      "id": "01JTESTSUB0000000000000001",
      "code": "SUB01",
      "curriculumProgramCode": "CUR01",
      "name": "Toán",
      "displayOrder": 1,
      "isActive": true
    },
    {
      "id": "01JTESTSUB0000000000000002",
      "code": "SUB02",
      "curriculumProgramCode": "CUR01",
      "name": "Vật lý",
      "displayOrder": 2,
      "isActive": true
    }
  ]
}

Ghi chú:

• Nếu chỉ truyền gradeCode, endpoint sẽ lấy danh sách môn được map với khối tương ứng
• Nếu truyền cả curriculumProgramCode và gradeCode, kết quả là giao của hai điều kiện lọc
• Kết quả được sắp xếp theo displayOrder, sau đó theo code

5.4. Tra cứu mapping khối và môn học

• Method: GET
• Path: /api/lms-base/publish/knowledge-units/subject-grades

Query params:

Response data[]:

Ví dụ curl:

curl --location "https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/publish/knowledge-units/subject-grades?gradeCode=10"

Ví dụ response:

{
  "success": true,
  "message": "Lấy danh sách mapping khối môn thành công.",
  "data": [
    {
      "id": "01JTESTSBG0000000000000001",
      "gradeCode": "10",
      "subjectCode": "0101",
      "curriculumProgramCode": "01",
      "subjectName": "Toán",
      "subjectOrder": 1
    },
    {
      "id": "01JTESTSBG0000000000000002",
      "gradeCode": "10",
      "subjectCode": "0102",
      "curriculumProgramCode": "01",
      "subjectName": "Vật lý",
      "subjectOrder": 2
    }
  ]
}

Ghi chú:

• Endpoint này hữu ích khi hệ thống nguồn đang quản lý riêng danh mục khối và danh mục môn, cần kiểm tra quan hệ hợp lệ trước khi gửi học liệu
• Kết quả được sắp xếp theo gradeCode, sau đó theo subjectCode

5.5. Tra cứu đơn vị kiến thức dạng phẳng

• Method: GET
• Path: /api/lms-base/publish/knowledge-units

Query params:

Response data[]:

Ví dụ curl:

curl --location "https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/publish/knowledge-units?curriculumProgramCode=CUR01&gradeCode=10&subjectCode=SUB01&activeOnly=true"

Ví dụ response:

{
  "success": true,
  "message": "Lấy danh sách đơn vị kiến thức thành công.",
  "data": [
    {
      "id": "01JTESTKUR0000000000000001",
      "code": "KU-ROOT-01",
      "name": "Hàm số bậc nhất",
      "targetLearning": "Nắm khái niệm hàm số bậc nhất",
      "parentCode": null,
      "curriculumProgramCode": "CUR01",
      "subjectCode": "SUB01",
      "gradeCode": "10",
      "displayOrder": 1,
      "isActive": true
    },
    {
      "id": "01JTESTKUC0000000000000001",
      "code": "KU-CHILD-01",
      "name": "Đồ thị hàm số bậc nhất",
      "targetLearning": "Vẽ được đồ thị",
      "parentCode": "KU-ROOT-01",
      "curriculumProgramCode": "CUR01",
      "subjectCode": "SUB01",
      "gradeCode": "10",
      "displayOrder": 2,
      "isActive": true
    }
  ]
}

Ghi chú:

• Endpoint trả về danh sách phẳng, không phải cây lồng nhau
• Quan hệ cha con được xác định qua parentCode
• Đây là endpoint nên dùng để lấy knowledgeUnitCode khi gọi API chia sẻ học liệu

6. Lưu ý tích hợp quan trọng

• activeOnly mặc định là true; nếu cần đồng bộ hoặc đối soát cả dữ liệu ngừng hoạt động thì truyền activeOnly=false
• Khi không có dữ liệu phù hợp, hệ thống vẫn trả 200 OK với data: []
• Dữ liệu tra cứu được cache theo từng tổ hợp query trong 300 giây; nếu danh mục vừa cập nhật, kết quả có thể chậm phản ánh tối đa khoảng 5 phút
• Nếu cùng một request được gọi lặp lại liên tục trong thời gian cache còn hiệu lực, response có thể chưa phản ánh bản ghi mới thêm ngay lập tức

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

• 200 OK: gọi thành công, kể cả trường hợp không có dữ liệu phù hợp
• 400 Bad Request: hiếm gặp, chủ yếu do query không bind được theo kiểu dữ liệu
• 401 Unauthorized: không áp dụng cho bộ API này trong implementation hiện tại vì controller cho phép gọi ẩn danh
• 404 Not Found: không áp dụng khi tra cứu danh sách; nếu không có dữ liệu, hệ thống trả mảng rỗng

8. Khuyến nghị sử dụng với API học liệu

• Luôn lấy mới subjectCode và knowledgeUnitCode từ bộ API này trước khi tạo học liệu nếu hệ thống nguồn không lưu đồng bộ master data với Trục LMS
• Nếu người dùng chọn môn theo khối, nên gọi subjects?gradeCode=... trước để chỉ hiển thị các môn hợp lệ
• Nếu cần dựng giao diện cây chương hoặc bài, lấy danh sách phẳng từ endpoint knowledge-units rồi tự nhóm lại theo parentCode ở phía client