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ả 2 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 POST /api/lms-base/learning-resources 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

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.
• 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.vstudy.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.
• Giai đoạn hiện tại hệ thống chưa xây dựng webhook/callback duyệt; cơ chế theo dõi là polling.

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.vstudy.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 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)
7. Poll API danh sách theo scope để theo dõi approvalStatus:
   • Nhà trường: GET /api/lms-base/learning-resources
   • Tổ chức: GET /api/lms-base/learning-resources/organizations
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

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.
  • Poll duyệt/xóa pending cũng theo đúng scope (/learning-resources hoặc /learning-resources/organizations).
• 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.
• Tổng từng file upload > 0 và <= 104857600 byte (100 MB).
• 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"
  ],
  "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
}

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ố",
      "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"
    }
  ]
}

Khi duyệt xong, approvalStatus đổi từ 0 sang:

• 1 (Approved)
• 2 (Rejected)

Nếu chia sẻ theo scope tổ chức, poll bằng endpoint:

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'

Response của endpoint tổ chức 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à <= 104857600 byte (100 MB).
• 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 100 MB, 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.
• Scope trường: doetCode/schoolCode/educationLevelCode được kiểm tra theo dữ liệu master; divisionCode nếu truyền cũng phải hợp lệ theo ngữ cảnh trường và năm học.
• Scope tổ chức: cho phép schoolCode = ""; hệ thống kiểm tra doetCode, không áp ngữ cảnh trường cho schoolCode/divisionCode.
• 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
• 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.
• 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 cả 2 endpoint.
• Có (scope trường): bắt buộc với POST /learning-resources; endpoint tổ chức có thể để trống để hệ thống tự gán.
• Không: không bắt buộc với cả 2 endpoint.

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.

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

• content không được chứa CSS/TypeScript/JavaScript.
• Không dùng iframe, object, embed.
• 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ế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ố",
  "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"
}

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. Cách theo dõi duyệt cho partner

• Giai đoạn hiện tại hệ thống chưa xây dựng webhook/callback cho duyệt.
• Cơ chế theo dõi đang dùng polling qua API danh sách theo scope:
  • Nhà trường: GET /api/lms-base/learning-resources
  • Tổ chức: GET /api/lms-base/learning-resources/organizations
• 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; theo dõi duyệt vẫn dùng API danh sách.
• Field trạng thái mới trong item response:
  • approvalStatusReason: lý do duyệt/từ chối (thường có khi Rejected).
  • approvalStatusDate: thời điểm ghi nhận trạng thái duyệt hiện tại.

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
• 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.
   • 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. 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.
12. URL trong TEXT HTML (src/href/poster) bắt buộc là URL tuyệt đối hợp lệ (http/https).
13. HTML không được chứa nội dung không an toàn (CSS/JS/iframe/object/embed/on*/protocol cấm).
14. semesterCode chỉ nhận 1 hoặc 2; yearCode phải là năm 4 chữ số hợp lệ.
15. API danh sách nhà trường bắt buộc doetCode; cả 2 API 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.

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?

• Giai đoạn hiện tại hệ thống chưa xây dựng webhook/callback duyệt.
• Cơ chế theo dõi đang là polling API danh sách theo scope:
  • Nhà trường: GET /learning-resources
  • Tổ chức: GET /learning-resources/organizations
• Nếu có roadmap webhook ở giai đoạn sau, nên phát hành spec riêng để partner triển khai tách biệt.

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
• 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: theo dõi bằng polling API danh sách, chưa có webhook/callback trong giai đoạn hiện tại.