Hướng dẫn tích hợp API Chia sẻ học liệu

Tài liệu này dành cho partner tích hợp lần đầu API chia sẻ học liệu trên Trục LMS (bao gồm luồng upload tệp đính kèm và chia sẻ học liệu).

Chọn nhánh triển khai

Chọn đúng tài liệu theo loại đơn vị để triển khai nhanh và giảm nhầm lẫn:

Trang này giữ vai trò tài liệu tổng quan + reference dùng chung cho cả 4 nhánh. Hướng dẫn tích hợp API tải học liệu đã duyệt: Tải học liệu đã duyệt.

Tích hợp nhanh

Happy path chuẩn:

1. Upload file qua POST /api/lms-base/attachments.
2. Nhận id và path cho từng file.
3. Replace URL trong HTML (src/href/poster) bằng path đã upload.
4. Gọi API upsert học liệu theo đúng scope với fileIds khớp đúng các file đang dùng.
5. Poll trạng thái duyệt qua endpoint danh sách tương ứng scope:
   • Nhà trường: GET /api/lms-base/learning-resources
   • Tổ chức: GET /api/lms-base/learning-resources/organizations
   • Sở: GET /api/lms-base/learning-resources/doets
   • Xã/phường: GET /api/lms-base/learning-resources/divisions

Lưu ý quan trọng:

• POST /learning-resources đang xử lý theo cơ chế upsert theo cặp schoolCode + sourceId trong phạm vi partner gọi API (X-Api-Key): nếu đã có bản ghi Pending/Rejected thì cập nhật, nếu chưa có thì tạo mới, nếu đã Approved thì bị từ chối.
• Nếu chia sẻ theo scope tổ chức, dùng POST /learning-resources/organizations; cơ chế upsert theo cặp partnerId + sourceId.
• Nếu chia sẻ theo scope Sở, dùng POST /learning-resources/doets; cơ chế upsert theo sourceId trong phạm vi partner + doetCode.
• Nếu chia sẻ theo scope xã/phường, dùng POST /learning-resources/divisions; cơ chế upsert theo sourceId trong phạm vi partner + doetCode + divisionCode.
• authorPinCode và creatorPinCode với endpoint POST /learning-resources phải là CCCD 12 số, tồn tại đúng ngữ cảnh dữ liệu Sở (doetCode/divisionCode/schoolCode/yearCode).
• gradeCode/subjectCode/knowledgeUnitCode phải map theo danh mục dùng chung: https://docs.hanoi.edu.vn/docs/knowledge-units.
• Nếu truyền fileIds, tất cả fileIds bắt buộc phải thực sự xuất hiện trong thumbnailUrl hoặc contents.
• Theo dõi trạng thái duyệt: ưu tiên dùng webhook (Trục chủ động gọi về partner khi đổi trạng thái — xem mục 7.6); có thể dùng polling API danh sách để đối soát/dự phòng.

1. Tổng quan bài toán

Bài toán tích hợp gồm 2 phần:

1. Quản lý file dùng trong học liệu (attachments).
2. Tạo bản ghi học liệu số (learning resource) và theo dõi duyệt.

Thông tin kết nối:

• Endpoint theo môi trường:
  • Môi trường Production (PROD): https://partner.hanoi.edu.vn/
  • Môi trường Development (DEV): https://lmsbpartnerapi.vstudy.edu.vn/
• Auth header: X-Api-Key: <api-key-don-vi-duoc-cap>
• JSON API: Content-Type: application/json
• Upload file: multipart/form-data cho /api/lms-base/attachments

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

Liên hệ cấp X-Api-Key

Thông tin dưới đây chỉ dùng cho việc cấp API key tích hợp Partner API:

Format response chung:

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

2. Luồng tích hợp end-to-end

1. Chuẩn bị metadata học liệu (sourceId, mã phân loại, thông tin tác giả/người gửi).
2. Upload các file/media sẽ được tham chiếu trong học liệu (ảnh đại diện nếu dùng ảnh đã upload, file trong contents, SCORM .zip nếu có). Với YOUTUBE, IFRAME hoặc thumbnailUrl dùng URL ngoài hợp lệ, không cần upload file tương ứng.
3. Lưu lại id + path từ response upload.
4. Replace URL trong contents[].content bằng path tương ứng; thumbnailUrl có thể dùng URL ảnh đã upload hoặc URL ảnh ngoài hợp lệ.
5. Tạo payload học liệu với fileIds khớp đúng file đang dùng.
6. Gọi API chia sẻ học liệu (upsert) theo scope phù hợp:
   • POST /api/lms-base/learning-resources (scope trường)
   • POST /api/lms-base/learning-resources/organizations (scope tổ chức)
   • POST /api/lms-base/learning-resources/doets (scope Sở)
   • POST /api/lms-base/learning-resources/divisions (scope xã/phường)
7. Poll API danh sách theo scope để theo dõi status:
   • Nhà trường: GET /api/lms-base/learning-resources
   • Tổ chức: GET /api/lms-base/learning-resources/organizations
   • Sở: GET /api/lms-base/learning-resources/doets
   • Xã/phường: GET /api/lms-base/learning-resources/divisions
8. Khi học liệu đã được duyệt và đủ điều kiện khai thác, tích hợp API tải theo tài liệu: Tải học liệu đã duyệt.
9. Nếu cần, kiểm tra trạng thái từng file bằng GET /api/lms-base/attachments/{attachmentId}.
10. Nếu cần thu hồi bản ghi đang chờ duyệt, gọi API xóa theo scope:

• Nhà trường: DELETE /api/lms-base/learning-resources
• Tổ chức: DELETE /api/lms-base/learning-resources/organizations
• Sở: DELETE /api/lms-base/learning-resources/doets
• Xã/phường: DELETE /api/lms-base/learning-resources/divisions

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

Checklist bắt buộc:

• Đã có X-Api-Key hợp lệ.
• Đã map đúng mã dùng chung của Sở (gradeCode, subjectCode, knowledgeUnitCode) từ danh mục knowledge-units.
• Với endpoint /learning-resources, đã xác thực authorPinCode/creatorPinCode đúng người, đúng ngữ cảnh (doetCode/divisionCode/schoolCode/yearCode).
• Đã chọn đúng endpoint theo scope chia sẻ:
  • POST /learning-resources: upsert theo schoolCode + sourceId trong phạm vi partner gọi API (X-Api-Key).
  • POST /learning-resources/organizations: upsert theo partnerId + sourceId.
  • POST /learning-resources/doets: upsert theo sourceId trong phạm vi partner + doetCode.
  • POST /learning-resources/divisions: upsert theo sourceId trong phạm vi partner + doetCode + divisionCode.
  • Poll duyệt/xóa pending cũng theo đúng scope tương ứng.
• Nếu sourceId đã có bản ghi Approved, phải dùng sourceId mới để chia sẻ tiếp (không cập nhật đè).
• File upload đúng loại MIME cho mục đích sử dụng.
• Giới hạn request upload của API là <= 1073741824 byte (1 GB); từng định dạng tệp vẫn có thể bị giới hạn thấp hơn theo cấu hình hệ thống.
• Tất cả URL trong thumbnailUrl và contents là URL tuyệt đối hợp lệ (http/https).
• Nếu có fileIds, mỗi id phải là ULID 26 ký tự, thuộc đúng partner và thực sự được dùng trong thumbnailUrl hoặc contents.
• HTML content không chứa thành phần bị cấm (CSS/JS/iframe/object/embed/on*/protocol không an toàn).

4. Quickstart với 1 ví dụ đầy đủ

4.1. Nội dung HTML ban đầu (before replace)

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

4.2. Upload file như thế nào

Upload từng file riêng qua POST /api/lms-base/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"'

{
  "success": true,
  "message": "Tải tệp thành công.",
  "data": {
    "id": "01JQ2S96MKZ8E8GHW8EXB4VPA7",
    "path": "https://<cdn-or-storage>/partner-code/thumb-phan-so.png",
    "useStatus": "Draft"
  }
}

Tương tự upload video và pdf (mỗi file 1 request), ví dụ nhận:

• 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

4.3. HTML sau khi replace URL (after replace)

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

4.4. Payload cuối cùng gửi lên learning-resources

{
  "sourceId": "LR-HN-000001",
  "title": "Bài học: So sánh phân số",
  "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",
    "01JQ2SCF3X7VY7S5M9N0B8K4Q1"
  ],
  "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"
    },
    {
      "name": "Video tải lên",
      "displayOrder": 2,
      "type": "VIDEO",
      "content": "https://<cdn-or-storage>/partner-code/video-phan-so-2.mp4",
      "description": "Video chính của học liệu"
    },
    {
      "name": "Video YouTube tham khảo",
      "displayOrder": 3,
      "type": "YOUTUBE",
      "content": "https://www.youtube.com/watch?v=d3bn7DVrZOw",
      "description": "Video tham khảo"
    }
  ],
  "gradeCode": "06",
  "subjectCode": "0601",
  "knowledgeUnitCode": "201100101",
  "doetCode": "01",
  "divisionCode": "0001",
  "schoolCode": "01000001",
  "yearCode": 2025,
  "educationLevelCode": "02",
  "semesterCode": 1
}

Gọi API:

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 '<payload-json-o-tren>'

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"
  }
}

operation có 2 giá trị:

• created: tạo mới học liệu.
• updated: cập nhật bản ghi đã có ở trạng thái Pending hoặc Rejected.

4.5. Poll trạng thái duyệt

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'

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ố",
      "status": "Pending",
      "reason": null,
      "occurredAt": "2026-04-12T07:12:44.0000000Z",
      "canDelete": true,
      "createdAt": "2026-04-12T07:12:44.0000000Z",
      "updatedAt": "2026-04-12T07:12:44.0000000Z"
    }
  ]
}

Trường status trong item response là chuỗi, gồm 5 giá trị: Pending, Approved, Rejected, Hidden, Removed. Khi duyệt/kiểm duyệt xong, status đổi từ Pending sang Approved/Rejected (hoặc về sau có thể là Hidden/Removed); với Rejected/Removed sẽ kèm reason.

Lưu ý: query param approvalStatus để lọc vẫn dùng số (0/1/2), độc lập với trường status dạng chuỗi trong response.

Nếu chia sẻ theo scope khác, poll bằng endpoint tương ứng:

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

Các endpoint polling theo scope:

• Nhà trường: GET /api/lms-base/learning-resources
• Tổ chức: GET /api/lms-base/learning-resources/organizations
• Sở: GET /api/lms-base/learning-resources/doets
• Xã/phường: GET /api/lms-base/learning-resources/divisions

Response giữa các endpoint có cùng cấu trúc (success, message, data[]).

5. Upload attachments

5.1. Upload tệp

• Method: POST
• Path: /api/lms-base/attachments
• Content-Type: multipart/form-data

Form-data fields:

Ràng buộc kỹ thuật:

• Kích thước file: > 0 và <= 1073741824 byte (1 GB).
• Tệp upload phải có phần mở rộng và phần mở rộng phải nằm trong danh mục hệ thống hỗ trợ.
• Ngoài giới hạn request 1 GB, hệ thống còn đối chiếu giới hạn dung lượng theo từng phần mở rộng từ cấu hình.
• MIME được kiểm tra theo chữ ký file (không chỉ extension).
• MIME được chấp nhận:
• image: image/jpeg, image/png, image/gif, image/webp.
• document: application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document.
• spreadsheet: application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.
• slide: application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation.
• video: video/mp4, video/webm.
• audio: audio/mpeg.
• scorm: application/zip.
• Nếu không truyền schoolCode: doetCode bắt buộc; divisionCode nếu có phải thuộc doetCode; educationLevelCode nếu có phải là mã cấp học hợp lệ.
• Nếu truyền schoolCode: hệ thống bắt buộc kiểm tra trường thuộc doetCode; educationLevelCode bắt buộc và phải khớp dữ liệu trường; divisionCode nếu có phải khớp với trường và theo đúng năm học dữ liệu trường.
• File upload phải được mapping dùng trong thumbnailUrl hoặc contents; file upload không được mapping sử dụng sẽ bị xóa khỏi hệ thống.
• Cơ chế dọn file không được mapping do hệ thống trục có job tự động quét dọn; partner không cần xử lý luồng này.

5.2. Kiểm tra trạng thái tệp

• Method: GET
• Path: /api/lms-base/attachments/{attachmentId}

Ví dụ response:

{
  "success": true,
  "message": "Lấy trạng thái tệp thành công.",
  "data": {
    "useStatus": "Used",
    "ownerId": "01JQ2T5W11Z9J6AEX4Q6F90HME",
    "accessUrl": "https://<cdn-or-storage>/partner-code/uuid.mp4"
  }
}

Ý nghĩa useStatus:

• Draft: file chưa gắn vào học liệu.
• Used: file đã gắn với một học liệu.

6. Tạo learning resource

6.1. Endpoint

• Method: POST
• Path (scope trường): /api/lms-base/learning-resources
• Path (scope tổ chức): /api/lms-base/learning-resources/organizations
• Path (scope Sở): /api/lms-base/learning-resources/doets
• Path (scope xã/phường): /api/lms-base/learning-resources/divisions
• Content-Type: application/json

Rule upsert theo endpoint:

• Scope trường (/learning-resources): xác định bản ghi theo schoolCode + sourceId trong phạm vi partner gọi API (X-Api-Key).
• Scope tổ chức (/learning-resources/organizations): xác định bản ghi theo partnerId + sourceId.
• Scope Sở (/learning-resources/doets): xác định bản ghi theo sourceId trong phạm vi partner + doetCode.
• Scope xã/phường (/learning-resources/divisions): xác định bản ghi theo sourceId trong phạm vi partner + doetCode + divisionCode.
• Nếu đã có bản ghi Approved, API từ chối cập nhật và yêu cầu sourceId mới.

6.2. Các trường request

Quy ước đọc cột Bắt buộc:

• Có: bắt buộc cho mọi scope chia sẻ.
• Có (scope trường): bắt buộc với POST /learning-resources.
• Có (scope trường, Sở, xã/phường): bắt buộc với 3 scope này; scope tổ chức được tự gán theo rule hệ thống.
• Có (scope xã/phường): chỉ bắt buộc với POST /learning-resources/divisions.
• Không: không bắt buộc, nhưng nếu truyền vẫn bị validate định dạng/độ dài.

6.3. Mapping mã dùng chung (bắt buộc)

Các trường phân loại học liệu phải dùng mã định danh do Sở quy định.

6.4. Cấu trúc contents[]

Rule content theo type:

Định dạng được hỗ trợ theo type:

• TEXT: nội dung inline.
• DOCUMENT: pdf, doc, docx.
• SPREADSHEET: xls, xlsx.
• VIDEO: mp4, webm.
• AUDIO: mp3.
• YOUTUBE: link YouTube tuyệt đối hợp lệ (không áp dụng định dạng file upload).
• SCORM: zip.
• SLIDE: ppt, pptx.
• IFRAME: URL tuyệt đối thuộc domain được phép (không áp dụng định dạng file upload).

Rule an toàn nội dung (bắt buộc):

• content không được chứa CSS/TypeScript/JavaScript.
• Trong HTML (TEXT/description) không được dùng thẻ iframe, object, embed. Muốn nhúng trang/công cụ ngoài, dùng nội dung loại IFRAME (truyền URL, không truyền thẻ <iframe>).
• Không dùng event handler dạng on*.
• Không dùng protocol/script không an toàn: javascript:, vbscript:, data:text/html, data:application/javascript.
• Chỉ hỗ trợ SCORM 1.2 hoặc 2004.
• Nội dung loại IFRAME chỉ chấp nhận URL tuyệt đối (http/https) có domain (hoặc subdomain) thuộc danh sách cho phép cấu hình ở LearningContentIframe:AllowedHosts (mặc định: youtube.com, olm.vn, sgk.olm.vn).
• Nếu truyền fileIds, tất cả fileIds phải được dùng trong thumbnailUrl hoặc contents; nếu không sẽ bị từ chối.

7. Tra cứu trạng thái duyệt

7.1. Endpoint danh sách học liệu nhà trường

• Method: GET
• Path: /api/lms-base/learning-resources
• Bắt buộc truyền doetCode trong query.

Query params:

Ví dụ gọi API:

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 'skip=0' \
  --data-urlencode 'take=20'

Ví dụ item response:

{
  "id": "01JQ2T5W11Z9J6AEX4Q6F90HME",
  "sourceId": "LR-HN-000001",
  "title": "Bài học: So sánh phân số",
  "status": "Rejected",
  "reason": "Nội dung chưa đúng chuẩn chương trình.",
  "occurredAt": "2026-04-12T07:12:44.0000000Z",
  "canDelete": false,
  "createdAt": "2026-04-12T07:12:44.0000000Z",
  "updatedAt": "2026-04-12T07:12:44.0000000Z"
}

Các trường trong item response:

Lưu ý: query param approvalStatus chỉ lọc theo 3 trạng thái duyệt (0=Pending, 1=Approved, 2=Rejected); chưa hỗ trợ lọc trực tiếp theo Hidden/Removed. Trường status trong response vẫn phản ánh đầy đủ 5 trạng thái.

7.2. Endpoint danh sách học liệu tổ chức

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

Query params (đều không bắt buộc):

Ví dụ gọi API:

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

7.3. Endpoint danh sách học liệu Sở

• Method: GET
• Path: /api/lms-base/learning-resources/doets
• Bắt buộc truyền doetCode trong query.

Query params:

7.4. Endpoint danh sách học liệu xã/phường

• Method: GET
• Path: /api/lms-base/learning-resources/divisions
• Bắt buộc truyền doetCode và divisionCode trong query.

Query params:

7.5. Cách theo dõi duyệt cho partner

Có 2 cơ chế theo dõi trạng thái duyệt:

• Webhook (khuyến nghị): Trục LMS chủ động gọi tới endpoint của partner mỗi khi học liệu đổi trạng thái. Chi tiết ở mục 7.6.
• Polling (dự phòng/đối soát): partner tự gọi API danh sách theo scope để tra cứu trạng thái.

Endpoint polling theo scope:

• Nhà trường: GET /api/lms-base/learning-resources
• Tổ chức: GET /api/lms-base/learning-resources/organizations
• Sở: GET /api/lms-base/learning-resources/doets
• Xã/phường: GET /api/lms-base/learning-resources/divisions

Lưu ý:

• Khuyến nghị lọc theo ngữ cảnh của đơn vị và theo approvalStatus để giảm dữ liệu trả về.
• Partner API hiện chưa có endpoint tra cứu trạng thái duyệt theo từng learningResourceId riêng biệt; tra cứu chủ động vẫn dùng API danh sách.
• Field trạng thái trong item response danh sách (xem chi tiết ở mục 7.1):
  • status: trạng thái hiện tại dạng chuỗi, gồm Pending, Approved, Rejected, Hidden, Removed.
  • reason: lý do theo trạng thái hiện tại (có khi Rejected/Removed).
  • occurredAt: thời điểm trạng thái hiện tại được ghi nhận (UTC).

7.6. Webhook đồng bộ trạng thái học liệu

Trục LMS hỗ trợ webhook để chủ động thông báo cho partner khi trạng thái học liệu thay đổi, giúp partner đồng bộ gần thời gian thực mà không phải polling liên tục.

7.6.1. Đăng ký webhook

Quy trình đăng ký (cấu hình ở phía Trục LMS theo từng đơn vị, không tự đăng ký qua API):

1. Đơn vị cần tích hợp webhook cung cấp cho QIG endpoint nhận sự kiện (WebhookUrl, khuyến nghị HTTPS).
2. QIG cấp lại cho đơn vị khóa bí mật webhook (WebhookSecret) dùng để ký/xác minh HMAC.
3. QIG bật webhook cho đơn vị sau khi có đủ thông tin.

Webhook chỉ được gửi khi đơn vị đang bật webhook và đã cấu hình đủ WebhookUrl + WebhookSecret.

Đầu mối liên hệ tích hợp webhook:

7.6.2. Sự kiện và thời điểm gửi

• eventType: learning-resource.status-changed.
• Webhook được gửi khi trạng thái học liệu thay đổi sang một trong các giá trị sau:

• Nếu trạng thái mới trùng trạng thái trước đó thì không gửi webhook.
• Trạng thái Pending không phát webhook.
• Nhiều học liệu của cùng một partner đổi trạng thái trong cùng một đợt xử lý sẽ được gom chung vào một event (mảng items).

7.6.3. Cấu trúc request gửi tới partner

• Method: POST tới WebhookUrl của partner.
• Content-Type: application/json.

Headers:

Body mẫu (JSON, key dạng camelCase):

{
  "eventId": "01JW1234567890ABCDEFGHJKL",
  "eventType": "learning-resource.status-changed",
  "occurredAt": "2026-05-25T03:15:20.1234567Z",
  "items": [
    { "sourceId": "LR-HN-000001", "status": "Approved", "reason": null },
    { "sourceId": "LR-HN-000002", "status": "Rejected", "reason": "Nội dung chưa đúng chuẩn chương trình." }
  ]
}

Trường payload:

7.6.4. Xác minh chữ ký (bắt buộc)

Partner phải xác minh X-Webhook-Signature trước khi xử lý payload:

1. Lấy timestamp = giá trị header X-Webhook-Timestamp.
2. Lấy payload = nguyên văn body request (raw UTF-8, không serialize lại).
3. Tính HMAC-SHA256 với khóa WebhookSecret trên chuỗi {timestamp}.{payload}.
4. Encode kết quả sang hex chữ thường và thêm tiền tố sha256=.
5. So sánh an toàn (constant-time) với header X-Webhook-Signature. Nếu khác → loại bỏ request.

Ví dụ tham khảo (Node.js):

const crypto = require("crypto");
 
function verifySignature(rawBody, timestamp, signatureHeader, webhookSecret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", webhookSecret).update(`${timestamp}.${rawBody}`).digest("hex");
 
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

7.6.5. Phản hồi và cơ chế retry

• Partner trả HTTP 2xx để xác nhận đã nhận; nên phản hồi nhanh và xử lý nghiệp vụ bất đồng bộ.
• Timeout mặc định mỗi lần gọi: 10 giây.
• Trục retry tối đa 3 lần khi gặp lỗi tạm thời: HTTP 408, 429, 5xx, lỗi mạng hoặc timeout.
• Các mã 4xx khác (trừ 408/429) được coi là lỗi vĩnh viễn và không retry.
• Vì có retry, partner phải chống trùng theo eventId (xử lý idempotent).

7.6.6. Khuyến nghị cho partner

• Dùng HTTPS cho WebhookUrl.
• Lưu eventId đã xử lý để bỏ qua sự kiện trùng.
• Vẫn nên có cron polling dự phòng (mục 7.5) để đối soát khi webhook lỗi kéo dài.
• Bảo mật WebhookSecret; phối hợp đầu mối để xoay khóa khi cần.

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

• Method: DELETE
• Path (scope trường): /api/lms-base/learning-resources
• Path (scope tổ chức): /api/lms-base/learning-resources/organizations
• Path (scope Sở): /api/lms-base/learning-resources/doets
• Path (scope xã/phường): /api/lms-base/learning-resources/divisions
• Content-Type: application/json

8.1. Dữ liệu đầu vào (request)

Request body là mảng string[] chứa danh sách id học liệu (ULID) cần xóa.

8.2. Mô hình phản hồi (response model)

API trả về response envelope chuẩn:

• success: true/false theo kết quả tổng thể của lô.
• message: thông điệp tổng hợp (ví dụ: số lượng thành công/thất bại).
• data: danh sách kết quả theo từng id đã gửi.

Chi tiết từng phần tử data[]:

Lưu ý: API có thể trả 200 OK nhưng vẫn có item deleted = false (thành công một phần), cần xử lý theo từng phần tử data[].

8.3. Ví dụ request

Ví dụ request:

[
  "01JQ2T5W11Z9J6AEX4Q6F90HME",
  "01JQ2T5W11Z9J6AEX4Q6F90HMF"
]

8.4. Ví dụ response (thành công một phần)

Ví dụ response:

{
  "success": false,
  "message": "Xử lý xóa 2 học liệu, xóa thành công 1, thất bại 1.",
  "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"
    },
    {
      "sourceId": "LR-HN-000002",
      "id": "01JQ2T5W11Z9J6AEX4Q6F90HMF",
      "deleted": false,
      "message": "Chỉ được xóa học liệu ở trạng thái chờ duyệt.",
      "processedAt": "2026-04-14T02:00:00.0000000Z"
    }
  ]
}

Ràng buộc xóa theo lô:

• Chỉ xóa được học liệu ở trạng thái Pending (0).
• Chỉ xóa được học liệu thuộc đúng đối tác gọi API (X-Api-Key).
• Tối đa 200 id/lần.
• Danh sách id không được rỗng và không được trùng trong cùng request.
• API có thể trả 200 OK nhưng có bản ghi xóa thất bại; luôn kiểm tra data[].deleted.

9. Các rule validate dễ sai

1. API tạo/chia sẻ học liệu chạy theo cơ chế upsert theo sourceId:
   • /learning-resources: key là schoolCode + sourceId trong phạm vi partner gọi API (X-Api-Key).
   • /learning-resources/organizations: key là partnerId + sourceId.
   • /learning-resources/doets: key là doetCode + sourceId trong phạm vi partner gọi API (X-Api-Key).
   • /learning-resources/divisions: key là doetCode + divisionCode + sourceId trong phạm vi partner gọi API (X-Api-Key).
   • Nếu bản ghi hiện tại đã Approved thì không được cập nhật đè.
2. authorPinCode/creatorPinCode ở endpoint /learning-resources phải là CCCD 12 số tồn tại trong hệ thống Sở theo đúng ngữ cảnh dữ liệu gửi lên.
3. gradeCode/subjectCode/knowledgeUnitCode không dùng mã tự đặt; phải map từ danh mục dùng chung.
4. sourceId, title, authorName, creatorName, contents[].name chỉ chấp nhận văn bản thuần, không chứa HTML.
5. description học liệu (nếu truyền) cho phép văn bản hoặc HTML an toàn, tối đa 1024 ký tự.
6. Khi tạo mới/cập nhật hợp lệ, hệ thống luôn gán trạng thái mặc định: ApprovalStatus = Pending (0) và ModerationStatus = Normal.
7. thumbnailUrl là bắt buộc và phải là URL tuyệt đối hợp lệ. Có thể dùng path ảnh đã upload hoặc URL ảnh ngoài đúng định dạng ảnh hỗ trợ.
8. contents là bắt buộc và phải có ít nhất 1 phần tử.
9. SCORM phải là URL tới .zip đã upload, đúng MIME application/zip, và đúng chuẩn SCORM hỗ trợ.
10. YOUTUBE phải là liên kết YouTube tuyệt đối hợp lệ (không truyền iframe HTML).
11. IFRAME phải là URL tuyệt đối (http/https) có domain/subdomain thuộc danh sách cho phép (mặc định youtube.com, olm.vn, sgk.olm.vn); không truyền thẻ <iframe> HTML.
12. fileIds nếu truyền thì tất cả phải thuộc partner và phải được dùng thực tế trong thumbnailUrl hoặc contents.
13. URL trong TEXT HTML (src/href/poster) bắt buộc là URL tuyệt đối hợp lệ (http/https).
14. HTML không được chứa nội dung không an toàn (CSS/JS/iframe/object/embed/on*/protocol cấm).
15. semesterCode chỉ nhận 1 hoặc 2; yearCode phải là năm 4 chữ số hợp lệ và tồn tại trong danh mục năm học hệ thống.
16. API danh sách:
    • Nhà trường: bắt buộc doetCode.
    • Tổ chức: không yêu cầu doetCode.
    • Sở: bắt buộc doetCode, không cho truyền divisionCode/schoolCode.
    • Xã/phường: bắt buộc doetCode + divisionCode, không cho truyền schoolCode.
    • Tất cả endpoint danh sách đều yêu cầu take trong khoảng 1..200 và skip >= 0.

10. Các lỗi thường gặp và cách xử lý

10.1. Theo HTTP status

10.2. Theo message nghiệp vụ thường gặp

11. FAQ cho partner

1) Có bắt buộc truyền fileIds không?

• Không bắt buộc.
• Nhưng nếu truyền thì tất cả id phải hợp lệ, thuộc partner, và được dùng thực tế trong thumbnailUrl hoặc contents.

2) authorPinCode và creatorPinCode có thể giống nhau không?

• Có thể giống hoặc khác.
• Với endpoint /learning-resources, cả hai phải là CCCD 12 số hợp lệ và tồn tại trong ngữ cảnh dữ liệu Sở.
• Với endpoint /learning-resources/organizations, có thể để trống để hệ thống tự điền mặc định theo thông tin tổ chức.
• Với endpoint /learning-resources/doets, hệ thống tự gán theo mã/tên Sở.
• Với endpoint /learning-resources/divisions, hệ thống tự gán theo mã/tên xã-phường.

3) Có thể gửi TEXT với HTML không?

• Có.
• Nhưng URL trong src/href/poster phải là URL tuyệt đối và nội dung phải qua rule an toàn HTML.

4) Có webhook/callback khi duyệt học liệu không?

• Có. Trục LMS chủ động gửi webhook learning-resource.status-changed tới WebhookUrl của partner khi học liệu đổi trạng thái sang Approved, Rejected, Hidden hoặc Removed. Chi tiết payload, headers, xác minh chữ ký và retry ở mục 7.6.
• Webhook cần được đầu mối cấp X-Api-Key cấu hình trước (WebhookUrl + WebhookSecret + bật webhook).
• Có thể kết hợp polling API danh sách theo scope để đối soát/dự phòng khi webhook lỗi kéo dài:
  • Nhà trường: GET /learning-resources
  • Tổ chức: GET /learning-resources/organizations
  • Sở: GET /learning-resources/doets
  • Xã/phường: GET /learning-resources/divisions

5) Khi nào được xóa học liệu?

• Chỉ xóa được học liệu ở trạng thái Pending (0) và thuộc đúng partner.

6) Tôi bị lỗi trùng sourceId, xử lý thế nào?

• Nếu bản ghi cùng key đang Approved, cần dùng sourceId mới để chia sẻ bản ghi mới.
• Nếu bản ghi cùng key đang Pending hoặc Rejected, API sẽ cập nhật bản ghi cũ và trả operation = updated.
• Khuyến nghị lưu mapping sourceId ở hệ thống nguồn để kiểm soát luồng upsert.

11.1. Quy ước vận hành đã chốt

• Scope upsert của sourceId:
  • /learning-resources: schoolCode + sourceId trong phạm vi X-Api-Key
  • /learning-resources/organizations: partnerId + sourceId
  • /learning-resources/doets: doetCode + sourceId trong phạm vi X-Api-Key
  • /learning-resources/divisions: doetCode + divisionCode + sourceId trong phạm vi X-Api-Key
• Cơ chế dọn file upload không được mapping: hệ thống trục có job tự động quét dọn.
• Trạng thái duyệt: ưu tiên webhook learning-resource.status-changed (mục 7.6); polling API danh sách dùng để đối soát/dự phòng.