Tích hợp cho Sở

Tài liệu này dành cho partner triển khai theo nhánh Sở với endpoint:

• POST /api/lms-base/learning-resources/doets

Nếu bạn tích hợp theo nhánh khác, tham chiếu:

• Tích hợp cho Nhà trường
• Tích hợp cho Tổ chức
• Tích hợp cho Xã/phường

1. Luồng tích hợp nhanh

1. Upload file qua POST /api/lms-base/attachments.
2. Nhận id + path của từng file upload.
3. Replace URL trong thumbnailUrl/contents bằng path đã upload (hoặc dùng URL ngoài hợp lệ theo rule).
4. Gọi POST /api/lms-base/learning-resources/doets (upsert theo doetCode + sourceId trong phạm vi X-Api-Key).
5. Poll duyệt bằng GET /api/lms-base/learning-resources/doets.

2. Rule nghiệp vụ chính

• doetCode là bắt buộc ở request chia sẻ và request tra cứu danh sách.
• divisionCode, schoolCode không bắt buộc cho scope Sở.
• authorPinCode, authorName, creatorPinCode, creatorName có thể để trống; hệ thống tự gán theo mã/tên Sở.
• Nếu đã tồn tại bản ghi cùng doetCode + sourceId:
  • Đang Pending/Rejected: cập nhật (operation=updated).
  • Đang Approved: từ chối cập nhật, phải dùng sourceId mới.

3. Endpoint tra cứu và xóa

• Theo dõi duyệt: khuyến nghị dùng webhook learning-resource.status-changed (xem Tổng quan tích hợp – mục 7.6); polling dưới đây dùng để đối soát/dự phòng.
• Tra cứu trạng thái: GET /api/lms-base/learning-resources/doets
  • Bắt buộc doetCode.
  • Không hỗ trợ lọc divisionCode, schoolCode.
• Xóa pending theo lô: DELETE /api/lms-base/learning-resources/doets
  • Request body: string[] danh sách ULID, tối đa 200 id/lần.
  • Chỉ xóa được bản ghi đang Pending.

4. Ví dụ gọi API chia sẻ (scope Sở)

curl --location 'https://partner.hanoi.edu.vn/api/lms-base/learning-resources/doets' \
  --header 'X-Api-Key: <api-key-don-vi-duoc-cap>' \
  --header 'Content-Type: application/json' \
  --data '{
    "sourceId": "LR-DOET-000001",
    "title": "Chuyên đề bồi dưỡng học sinh giỏi Toán",
    "description": "Nội dung tham khảo cấp Sở.",
    "thumbnailUrl": "https://<cdn-or-storage>/partner-code/thumb.png",
    "authorPinCode": "",
    "authorName": "",
    "creatorPinCode": "",
    "creatorName": "",
    "fileIds": [
      "01JQ2S96MKZ8E8GHW8EXB4VPA7",
      "01JQ2SAXA9QXRVQ8S9QPA4J2AN"
    ],
    "contents": [
      {
        "name": "Video tải lên",
        "displayOrder": 1,
        "type": "VIDEO",
        "content": "https://<cdn-or-storage>/partner-code/video-doet.mp4",
        "description": "Video chính"
      },
      {
        "name": "Video YouTube tham khảo",
        "displayOrder": 2,
        "type": "YOUTUBE",
        "content": "https://www.youtube.com/watch?v=d3bn7DVrZOw",
        "description": "Video tham khảo"
      }
    ],
    "gradeCode": "12",
    "subjectCode": "0201",
    "knowledgeUnitCode": "0201040400",
    "doetCode": "01",
    "divisionCode": "",
    "schoolCode": "",
    "yearCode": 2025,
    "educationLevelCode": "04",
    "semesterCode": 2
  }'

Chi tiết toàn bộ field/rule: Tổng quan tích hợp.