Tích hợp cho Nhà trường | QIG LMS Docs

Tài liệu này dành cho partner triển khai theo nhánh Nhà trường với endpoint:

POST /api/lms-base/learning-resources

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).

Nếu bạn tích hợp theo nhánh tổ chức, chuyển sang Tích hợp cho Tổ chức.

1. Luồng tích hợp nhanh (happy path)

Upload file qua POST /api/lms-base/attachments.
Nhận id + path của từng file upload.
Replace URL trong HTML (src/href/poster) bằng path đã upload.
Gọi POST /api/lms-base/learning-resources (upsert theo schoolCode + sourceId trong phạm vi X-Api-Key).
Poll duyệt bằng GET /api/lms-base/learning-resources với approvalStatus.

2. Checklist trước khi gọi API

Đã có X-Api-Key hợp lệ.
sourceId là mã do partner quản lý và dùng ổn định trong scope schoolCode của chính X-Api-Key đang gọi; chỉ chấp nhận văn bản thuần, không chứa HTML.
authorPinCode và creatorPinCode là CCCD 12 số hợp lệ theo đúng ngữ cảnh dữ liệu Sở (doetCode/divisionCode/schoolCode/yearCode).
gradeCode/subjectCode/knowledgeUnitCode map đúng danh mục dùng chung: knowledge-units.
title, authorName, creatorName, contents[].name chỉ chấp nhận văn bản thuần, không chứa HTML.
description (nếu truyền) cho phép văn bản hoặc HTML an toàn, tối đa 1024 ký tự.
thumbnailUrl là bắt buộc và phải là URL tuyệt đối hợp lệ (ảnh đã upload hoặc URL ảnh ngoài đúng định dạng hỗ trợ).
contents là bắt buộc và phải có ít nhất 1 phần tử.
Mỗi file upload > 0 và <= 104857600 bytes (100 MB), đúng MIME theo loại nội dung.
Nếu có fileIds, tất cả id phải được dùng thực sự trong thumbnailUrl hoặc contents.
contents kiểu TEXT không chứa thành phần HTML cấm (iframe, object, embed, script/CSS không an toàn...).
contents kiểu YOUTUBE chỉ nhận URL dạng https://youtube.com/watch?v=... (bao gồm www.youtube.com/watch?v=...) hoặc https://youtu.be/..., không gửi iframe/embed.

3. Ví dụ end-to-end

3.1. HTML ban đầu

<p>Xem video minh họa:</p>
<video controls poster="https://partner.example.com/media/thumb-phan-so.png">
  <source src="https://partner.example.com/media/video-phan-so.mp4" type="video/mp4" />
</video>
<p>Tải tài liệu PDF: <a href="https://partner.example.com/media/phieu-bai-tap.pdf">Tại đây</a></p>

html

3.2. Upload attachments

curl --location 'https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/attachments' \
  --header 'X-Api-Key: <api-key-don-vi-duoc-cap>' \
  --form 'doetCode="01"' \
  --form 'divisionCode="0001"' \
  --form 'schoolCode="01000001"' \
  --form 'educationLevelCode="02"' \
  --form 'file=@"/path/to/thumb-phan-so.png"'

bash

Ví dụ kết quả upload:

Thumbnail: id=01JQ2S96MKZ8E8GHW8EXB4VPA7, path=https://<cdn-or-storage>/partner-code/thumb-phan-so.png
Video: id=01JQ2SAXA9QXRVQ8S9QPA4J2AN, path=https://<cdn-or-storage>/partner-code/video-phan-so.mp4
PDF: id=01JQ2SB6R52J01Q2RC9F0M6V7P, path=https://<cdn-or-storage>/partner-code/phieu-bai-tap.pdf

3.3. HTML sau replace URL

<p>Xem video minh họa:</p>
<video controls poster="https://<cdn-or-storage>/partner-code/thumb-phan-so.png">
  <source src="https://<cdn-or-storage>/partner-code/video-phan-so.mp4" type="video/mp4" />
</video>
<p>Tải tài liệu PDF: <a href="https://<cdn-or-storage>/partner-code/phieu-bai-tap.pdf">Tại đây</a></p>

html

3.4. Gọi create/update học liệu (scope trường)

curl --location 'https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/learning-resources' \
  --header 'X-Api-Key: <api-key-don-vi-duoc-cap>' \
  --header 'Content-Type: application/json' \
  --data '{
    "sourceId": "LR-HN-000001",
    "title": "Bài học: So sánh phân số",
    "description": "Bài học củng cố kiến thức so sánh phân số cho học sinh lớp 6.",
    "thumbnailUrl": "https://<cdn-or-storage>/partner-code/thumb-phan-so.png",
    "authorPinCode": "001095123456",
    "authorName": "Nguyen Van A",
    "creatorPinCode": "001095123456",
    "creatorName": "Nguyen Van A",
    "fileIds": [
      "01JQ2S96MKZ8E8GHW8EXB4VPA7",
      "01JQ2SAXA9QXRVQ8S9QPA4J2AN",
      "01JQ2SB6R52J01Q2RC9F0M6V7P"
    ],
    "contents": [
      {
        "name": "Mở đầu",
        "displayOrder": 1,
        "type": "TEXT",
        "content": "<p>Xem video minh họa:</p><video controls poster=\"https://<cdn-or-storage>/partner-code/thumb-phan-so.png\"><source src=\"https://<cdn-or-storage>/partner-code/video-phan-so.mp4\" type=\"video/mp4\" /></video><p>Tải tài liệu PDF: <a href=\"https://<cdn-or-storage>/partner-code/phieu-bai-tap.pdf\">Tại đây</a></p>",
        "description": "Mở đầu"
      }
    ],
    "gradeCode": "06",
    "subjectCode": "0601",
    "knowledgeUnitCode": "201100101",
    "doetCode": "01",
    "divisionCode": "0001",
    "schoolCode": "01000001",
    "yearCode": 2025,
    "educationLevelCode": "02",
    "semesterCode": 1
  }'

bash

Response thành công:

{
  "success": true,
  "message": "Tạo mới học liệu số thành công.",
  "data": {
    "sourceId": "LR-HN-000001",
    "id": "01JQ2T5W11Z9J6AEX4Q6F90HME",
    "approvalStatus": 0,
    "operation": "created"
  }
}

json

operation:

created: tạo mới.
updated: cập nhật bản ghi cùng schoolCode + sourceId trong phạm vi X-Api-Key khi bản ghi cũ đang Pending hoặc Rejected.

4. Theo dõi duyệt (polling)

Hiện tại chưa có webhook/callback duyệt trong tài liệu Partner API. Theo dõi duyệt bằng polling:

Lưu ý: với endpoint danh sách nhà trường, doetCode là query bắt buộc.

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

bash

Response thành công:

{
  "success": true,
  "message": "Lấy danh sách học liệu thành công.",
  "data": [
    {
      "id": "01JQ2T5W11Z9J6AEX4Q6F90HME",
      "sourceId": "LR-HN-000001",
      "title": "Bài học: So sánh phân số",
      "approvalStatus": 0,
      "approvalStatusReason": null,
      "approvalStatusDate": "2026-04-12T07:12:44.0000000Z",
      "canDelete": true,
      "createdAt": "2026-04-12T07:12:44.0000000Z",
      "updatedAt": "2026-04-12T07:12:44.0000000Z"
    }
  ]
}

json

approvalStatusReason và approvalStatusDate phản ánh lý do/thời điểm của trạng thái duyệt hiện tại.

Trạng thái:

0: Pending
1: Approved
2: Rejected

5. Xóa học liệu pending

Chỉ xóa được bản ghi do partner tạo và còn Pending:

5.1. Dữ liệu đầu vào

Request body: string[] (danh sách id ULID học liệu cần xóa).
Ràng buộc: mảng không rỗng, không trùng id, tối đa 200 id/lần.

5.2. Mô hình phản hồi

API trả về envelope: success, message, data.
data[] gồm: sourceId, id, deleted, message, processedAt.
Có thể xảy ra thành công một phần: HTTP 200 nhưng một số phần tử có deleted = false.

5.3. Ví dụ request

curl --location --request DELETE 'https://lmsbpartnerapi.vstudy.edu.vn/api/lms-base/learning-resources' \
  --header 'X-Api-Key: <api-key-don-vi-duoc-cap>' \
  --header 'Content-Type: application/json' \
  --data '[
    "01JQ2T5W11Z9J6AEX4Q6F90HME"
  ]'

bash

5.4. Ví dụ response

Response thành công:

{
  "success": true,
  "message": "Xử lý xóa 1 học liệu, xóa thành công 1, thất bại 0.",
  "data": [
    {
      "sourceId": "LR-HN-000001",
      "id": "01JQ2T5W11Z9J6AEX4Q6F90HME",
      "deleted": true,
      "message": "Xóa học liệu thành công.",
      "processedAt": "2026-04-14T02:00:00.0000000Z"
    }
  ]
}

json

6. Reference dùng chung

Tài liệu tổng quan + rule validate đầy đủ: Hướng dẫn tích hợp API Chia sẻ học liệu
Hướng dẫn API tải học liệu đã duyệt: Tải học liệu đã duyệt
Danh mục mapping mã dùng chung: knowledge-units