Logo HanoiStudyTài liệu Trục LMS Hà Nội
Tìm kiếm tài liệu...
Mẹo tìm kiếm
Hỏi bằng tiếng Việt. AI sẽ tìm đúng nội dung trong docs cho bạn.

Tải học liệu đã duyệt

Hướng dẫn tích hợp API download học liệu đã duyệt và cơ chế ghi nhận lượt tải cho đơn vị.

Tài liệu này mô tả nhóm API download học liệu trên Trục LMS:

  • GET /api/lms-base/learning-resources/download
  • GET /api/lms-base/learning-resources/{id}/download
  • POST /api/lms-base/learning-resources/download/batch

Môi trường endpoint:

  • Môi trường Production (PROD): https://partner.vstudy.edu.vn/
  • Môi trường Development (DEV): https://lmsbpartnerapi.vstudy.edu.vn/

Lưu ý: các ví dụ curl trong tài liệu này đang dùng endpoint môi trường Development (DEV). Khi triển khai thật, đổi sang môi trường Production (PROD).

Header dùng chung:

  • X-Api-Key: <api-key-don-vi-duoc-cap>
  • Content-Type: application/json (cho API POST)

1. Quy tắc nghiệp vụ download

  • Chỉ tải được học liệu có ApprovalStatus = Approved.
  • Trạng thái kiểm duyệt cho phép tải: ModerationStatus in (Normal, ReviewedSafe).
  • Học liệu Pending, Rejected, Hidden, Removed, UnderReview không cho tải.
  • Khi tải thành công, hệ thống tự ghi nhận lượt tải theo đơn vị tải.
  • Lượt tải được ghi nhận theo ngữ cảnh đơn vị tải: DoetCode, DivisionCode, SchoolCode, EducationLevelCode (không theo đơn vị chia sẻ học liệu).

1.1. Lưu ý triển khai bắt buộc cho đơn vị tích hợp

  • Sau khi tải học liệu thành công, đơn vị cần tải đầy đủ tất cả file/media liên quan về lưu trữ cục bộ tại LMS của đơn vị:
    • thumbnailUrl
    • các URL file/media trong contents[].content (bao gồm URL trong src/href/poster nếu type=TEXT)
    • với type=SCORM, tải file package .zip gốc
  • Khi hiển thị học liệu trên LMS của đơn vị, nên dùng URL nội bộ đã lưu cục bộ thay vì phụ thuộc trực tiếp URL trên trục.
  • Mục tiêu là bảo đảm học liệu vẫn sử dụng được ổn định nếu sau này học liệu trên trục bị gỡ bỏ, thay đổi đường dẫn, hoặc thay đổi quyền truy cập.

2. Tra cứu danh sách học liệu cho phép tải

  • Method: GET
  • Path: /api/lms-base/learning-resources/download

2.1. Query params

FieldKiểu dữ liệuGiới hạnBắt buộcGhi chú
educationLevelCodestring / nullTối đa 20 ký tựKhôngLọc theo cấp học
doetCodestring / nullTối đa 20 ký tựKhôngLọc theo Sở GDĐT
divisionCodestring / nullTối đa 20 ký tựKhôngLọc theo xã/phường
schoolCodestring / nullTối đa 50 ký tựKhôngLọc theo trường
gradeCodestring / nullTối đa 20 ký tựKhôngLọc theo khối
subjectCodestring / nullTối đa 20 ký tựKhôngLọc theo môn
orderByint / null1 hoặc 2Không1=ViewCount, 2=LikeCount. Mặc định: 1
skipint / null>= 0KhôngMặc định 0
takeint / null1..200KhôngMặc định 20

Ví dụ:

curl --location --get 'https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/learning-resources/download' \
  --header 'X-Api-Key: <api-key-don-vi-duoc-cap>' \
  --data-urlencode 'doetCode=01' \
  --data-urlencode 'educationLevelCode=02' \
  --data-urlencode 'orderBy=1' \
  --data-urlencode 'skip=0' \
  --data-urlencode 'take=20'
bash

items[].contents ở API này chỉ trả metadata nội dung (id, name, type, displayOrder, description), không trả trường content.

Ví dụ response:

{
  "success": true,
  "message": "Lấy danh sách học liệu tải về thành công.",
  "data": {
    "total": 120,
    "skip": 0,
    "take": 20,
    "items": [
      {
        "id": "01KPPVMHC7Z9BTY2P6XGW3F1GF",
        "title": "Bài học: So sánh phân số",
        "thumbnailUrl": "https://cdn.example.vn/partner/thumb-phan-so.png",
        "doetCode": "01",
        "divisionCode": "0001",
        "divisionName": "Phường A",
        "schoolCode": "0100004006",
        "schoolName": "THCS B",
        "educationLevelCode": "04",
        "educationLevelName": "Trung học cơ sở",
        "yearCode": 2025,
        "yearName": "Năm học 2025-2026",
        "semesterCode": 1,
        "semesterName": "Học kỳ 1",
        "gradeCode": "06",
        "gradeName": "Lớp 6",
        "subjectCode": "0601",
        "subjectName": "Toán",
        "knowledgeUnitCode": "201100101",
        "knowledgeUnitName": "So sánh phân số",
        "authorName": "Nguyễn Văn A",
        "viewCount": 1200,
        "likeCount": 230,
        "downloadCount": 58,
        "contents": [
          {
            "id": "01KPPVQ0PKY33AYZ6T72PC6C2V",
            "learningResourceId": "01KPPVMHC7Z9BTY2P6XGW3F1GF",
            "name": "Nội dung chính",
            "displayOrder": 1,
            "type": "TEXT",
            "description": "Mô tả ngắn"
          }
        ],
        "createdAt": "2026-04-20T08:30:00Z",
        "updatedAt": "2026-04-22T10:00:00Z"
      }
    ]
  }
}
json

3. Tải chi tiết 1 học liệu

  • Method: GET
  • Path: /api/lms-base/learning-resources/{id}/download

3.1. Query params đơn vị tải

FieldKiểu dữ liệuBắt buộcGiới hạnGhi chú
doetCodestringCóTối đa 20 ký tựMã Sở của đơn vị tải
divisionCodestring / nullKhôngTối đa 20 ký tựMã xã/phường quản lý của đơn vị tải
schoolCodestringCóTối đa 50 ký tựMã trường của đơn vị tải
educationLevelCodestringCóTối đa 20 ký tựMã cấp học của đơn vị tải
contentIdsarray<string> / nullKhôngTối đa 200 ULID/lầnNếu bỏ trống thì trả toàn bộ nội dung; nếu truyền thì mỗi id phải thuộc học liệu

Ví dụ tải toàn bộ nội dung:

curl --location --get 'https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/learning-resources/01KPPVMHC7Z9BTY2P6XGW3F1GF/download' \
  --header 'X-Api-Key: <api-key-don-vi-duoc-cap>' \
  --data-urlencode 'doetCode=01' \
  --data-urlencode 'schoolCode=0100004006' \
  --data-urlencode 'educationLevelCode=04'
bash

Ví dụ tải chọn lọc theo nội dung:

curl --location --get 'https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/learning-resources/01KPPVMHC7Z9BTY2P6XGW3F1GF/download' \
  --header 'X-Api-Key: <api-key-don-vi-duoc-cap>' \
  --data-urlencode 'doetCode=01' \
  --data-urlencode 'schoolCode=0100004006' \
  --data-urlencode 'educationLevelCode=04' \
  --data-urlencode 'contentIds=01KPPVQ0PKY33AYZ6T72PC6C2V'
bash

Ví dụ response:

{
  "success": true,
  "message": "Tải dữ liệu học liệu thành công.",
  "data": {
    "id": "01KPPVMHC7Z9BTY2P6XGW3F1GF",
    "title": "Bài học: So sánh phân số",
    "partnerName": "LMS Partner A",
    "thumbnailUrl": "https://cdn.example.vn/partner/thumb-phan-so.png",
    "doetCode": "01",
    "divisionCode": "0001",
    "divisionName": "Phường A",
    "schoolCode": "0100004006",
    "schoolName": "THCS B",
    "educationLevelCode": "04",
    "educationLevelName": "Trung học cơ sở",
    "yearCode": 2025,
    "yearName": "Năm học 2025-2026",
    "semesterCode": 1,
    "semesterName": "Học kỳ 1",
    "gradeCode": "06",
    "gradeName": "Lớp 6",
    "subjectCode": "0601",
    "subjectName": "Toán",
    "knowledgeUnitCode": "201100101",
    "knowledgeUnitName": "So sánh phân số",
    "authorName": "Nguyễn Văn A",
    "contents": [
      {
        "id": "01KPPVQ0PKY33AYZ6T72PC6C2V",
        "learningResourceId": "01KPPVMHC7Z9BTY2P6XGW3F1GF",
        "name": "Nội dung chính",
        "displayOrder": 1,
        "type": "TEXT",
        "content": "<p>Nội dung đã chuẩn hóa</p>",
        "description": "Mô tả ngắn"
      },
      {
        "id": "01KPPVQ57SP4J5N7VE6P0E4G5A",
        "learningResourceId": "01KPPVMHC7Z9BTY2P6XGW3F1GF",
        "name": "Bài giảng SCORM",
        "displayOrder": 2,
        "type": "SCORM",
        "content": "https://cdn.example.vn/partner/scorm/bai-giang.zip",
        "description": "SCORM gốc để tải"
      }
    ],
    "createdAt": "2026-04-20T08:30:00Z",
    "updatedAt": "2026-04-22T10:00:00Z"
  }
}
json

Lưu ý SCORM khi download:

  • contents[].content của type=SCORM trả về URL package .zip gốc để đơn vị tải xuống.
  • Không trả URL trang view SCORM nội bộ của hệ thống.

4. Tải theo lô nhiều học liệu

  • Method: POST
  • Path: /api/lms-base/learning-resources/download/batch

Request body:

{
  "doetCode": "01",
  "divisionCode": "0001",
  "schoolCode": "0100004006",
  "educationLevelCode": "04",
  "ids": [
    "01KPPVMHC7Z9BTY2P6XGW3F1GF",
    "01KPPVMHC7Z9BTY2P6XGW3F1GG"
  ]
}
json

Ràng buộc:

  • ids bắt buộc, không rỗng.
  • Tối đa 200 id/lần.
  • Mỗi id phải đúng định dạng ULID.
  • Trùng id trong cùng request sẽ bị từ chối.
  • Kết quả có thể thành công một phần; cần đọc data[].success.

Ví dụ response tải lô (thành công một phần):

{
  "success": false,
  "message": "Xử lý tải 2 học liệu, thành công 1, thất bại 1.",
  "data": [
    {
      "id": "01KPPVMHC7Z9BTY2P6XGW3F1GF",
      "success": true,
      "message": "Tải dữ liệu học liệu thành công.",
      "data": {
        "id": "01KPPVMHC7Z9BTY2P6XGW3F1GF",
        "title": "Bài học: So sánh phân số",
        "contents": [
          {
            "id": "01KPPVQ0PKY33AYZ6T72PC6C2V",
            "learningResourceId": "01KPPVMHC7Z9BTY2P6XGW3F1GF",
            "name": "Nội dung chính",
            "displayOrder": 1,
            "type": "TEXT",
            "content": "<p>Nội dung đã chuẩn hóa</p>",
            "description": "Mô tả ngắn"
          }
        ]
      }
    },
    {
      "id": "01KPPVMHC7Z9BTY2P6XGW3F1GG",
      "success": false,
      "message": "Không tìm thấy học liệu.",
      "data": null
    }
  ]
}
json

5. Ghi nhận lượt tải

Các API tải chi tiết (GET {id}/download) và tải lô (POST download/batch) tự động ghi nhận lượt tải khi xử lý thành công.

  • Nếu ghi nhận lượt tải lỗi, API trả thông báo:
    • Không thể ghi nhận lượt tải học liệu ở thời điểm hiện tại.
  • Với tải lô, lỗi có thể xảy ra theo từng phần tử trong data[].

6. Lỗi thường gặp

Message lỗiNguyên nhânCách xử lý
Chỉ cho phép tải học liệu đã duyệt và không thuộc trạng thái tạm ẩn/gỡ bỏ.Học liệu chưa đạt điều kiện tảiChỉ tải học liệu đã duyệt, trạng thái kiểm duyệt cho phép
Mã sở giáo dục của đơn vị tải là bắt buộc.Thiếu doetCodeBổ sung doetCode hợp lệ
Mã trường của đơn vị tải là bắt buộc.Thiếu schoolCodeBổ sung schoolCode hợp lệ
Mã cấp học của đơn vị tải là bắt buộc.Thiếu educationLevelCodeBổ sung educationLevelCode hợp lệ
Số lượng ContentIds tối đa trong một lần tải là 200.Truyền quá số lượng cho phépChia nhỏ request
ContentId không thuộc học liệu: ...contentIds không nằm trong học liệu yêu cầuLấy lại danh sách nội dung đúng của học liệu rồi gọi lại
Số lượng Id tối đa trong một lần tải là 200.Tải lô vượt giới hạnChia nhỏ theo lô
Không tìm thấy học liệu.Id không tồn tại hoặc không còn khả dụngKiểm tra lại id trước khi tải

7. Reference liên quan

Trước đó
Tích hợp cho Tổ chức
Tiếp theo
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