Tổng quan tích hợp DTI | QIG LMS Docs

Tài liệu này cung cấp thông tin tổng quan để các đơn vị LMS tích hợp đẩy chỉ số thống kê lên hệ thống DTI — phục vụ Dashboard chuyển đổi số giáo dục.

1. Thông tin kết nối

Base URL: https://dtiapi.vstudy.edu.vn/api/v1
Swagger UI: https://dtiapi.vstudy.edu.vn/api-docs/ (user: admin / pass: dti@2026)
Xác thực: Header X-Api-Key: <api-key-don-vi-duoc-cap>
Content-Type: application/json

Để được cấp X-Api-Key, vui lòng liên hệ đơn vị QIG.

Tất cả response dùng format chung:

{
  "error_code": 0,
  "data": {},
  "message": "OK"
}

json

Response lỗi:

{
  "error_code": 2005,
  "message": "Thời gian đo không hợp lệ.",
  "data": null
}

json

2. Luồng tích hợp

1. GET /api/v1/lms/hub/metrics/push-config   → Lấy danh sách metrics cần push + tần suất
2. GET /api/v1/lms/hub/dimensions            → Lấy danh sách dimension values (content_type, device, ...)
3. LMS thu thập dữ liệu theo push_interval
4. POST /api/v1/lms/hub/push                 → Đẩy chỉ số cấp trường (batch tối đa 500 trường)
5. POST /api/v1/lms/hub/push/users           → Đẩy chỉ số cấp user (tối đa 500 users/request)
6. POST /api/v1/lms/hub/push/schools         → Đẩy thông tin trường (has_lms, shared_to_hub) — 1 lần/ngày

Phân biệt 3 loại push

	School metrics	User metrics	School profiles
API	`POST /hub/push`	`POST /hub/push/users`	`POST /hub/push/schools`
Batch	Tối đa 500 trường/request	1 trường, tối đa 500 users/request	Tối đa 500 trường/request
Tần suất	Mỗi giờ hoặc mỗi ngày	Mỗi giờ hoặc mỗi ngày	1 lần/ngày
Nội dung	Chỉ số tổng trường (accounts, rates, storage, sharing...)	Chỉ số per-user (lessons, tests, exercises, duration...)	Trạng thái trường (has_lms, shared_to_hub)
Tài liệu	Chi tiết	Chi tiết	Chi tiết

3. Lấy cấu hình push

3.1. Danh sách metrics

Method: GET
Path: /api/v1/lms/hub/metrics/push-config

Response trả về danh sách metrics gom theo push_interval:

{
  "data": [
    {
      "push_interval": "1 hour",
      "metrics": [
        { "key": "online_students", "name": "Số HS đang trực tuyến", "value_type": "gauge", "unit": "students", "dim_type": null, "target_role": null, "requires_subject_code": false, "requires_grade_code": false }
      ]
    },
    {
      "push_interval": "1 day",
      "metrics": [
        { "key": "teacher_accounts", "name": "Số tài khoản giáo viên", "value_type": "cumulative", "unit": "accounts", "dim_type": null, "target_role": null, "requires_subject_code": false, "requires_grade_code": false },
        { "key": "total_lessons", "name": "Số lượng bài giảng", "value_type": "cumulative", "unit": "lessons", "dim_type": "content_type", "target_role": "teacher", "requires_subject_code": true, "requires_grade_code": true }
      ]
    }
  ]
}

json

Mô tả các fields:

Field	Mô tả
`key`	Mã định danh metric (dùng trong payload push)
`name`	Tên hiển thị metric
`value_type`	`cumulative` (tích lũy) hoặc `gauge` (snapshot tại thời điểm)
`unit`	Đơn vị: lessons, accounts, %, GB, minutes, ...
`dim_type`	Loại dimension (nếu có). Khi `dim_type` không null, cần gửi kèm `dim_value` trong payload
`target_role`	`teacher` hoặc `student` = metric cấp user (push qua `/hub/push/users`). `null` = metric cấp trường (push qua `/hub/push`)
`requires_subject_code`	Nếu `true`, metric bắt buộc gửi kèm `subject_code`. Thiếu sẽ bị reject
`requires_grade_code`	Nếu `true`, metric bắt buộc gửi kèm `grade_code`. Thiếu sẽ bị reject
`push_interval`	Tần suất push khuyến nghị: `1 hour`, `1 day`, `1 week`, `1 month`

3.2. Danh sách dimensions

Method: GET
Path: /api/v1/lms/hub/dimensions

Trả về registry dimension types kèm danh sách values hợp lệ:

{
  "data": [
    {
      "key": "content_type",
      "name": "Loại bài giảng",
      "values": [
        { "code": "video", "label": "Video", "sort_order": 2 },
        { "code": "scorm", "label": "Scorm", "sort_order": 5 },
        { "code": "document", "label": "Tài liệu", "sort_order": 4 },
        { "code": "audio", "label": "Âm thanh", "sort_order": 3 },
        { "code": "content", "label": "Nội dung thuần", "sort_order": 1 },
        { "code": "iframe", "label": "IFrame", "sort_order": 6 },
        { "code": "test", "label": "Bài kiểm tra", "sort_order": 7 },
        { "code": "interactive_video", "label": "Video tương tác", "sort_order": 8 }
      ]
    },
    {
      "key": "device",
      "name": "Thiết bị",
      "values": [
        { "code": "mobile", "label": "Mobile", "sort_order": 1 },
        { "code": "pc", "label": "PC", "sort_order": 2 },
        { "code": "tablet", "label": "Tablet", "sort_order": 3 }
      ]
    }
  ]
}

json

3.3. Giải thích subject_code và grade_code

Một số metrics theo môn/khối sử dụng 2 fields:

subject_code (tối đa 4 ký tự số): mã chương trình môn học
grade_code (2 ký tự số): mã khối/lớp

Danh mục mã chương trình môn học sẽ do Sở GD&ĐT ban hành. subject_code phục vụ breakdown theo môn học, grade_code phục vụ breakdown theo khối lớp.

Quan trọng: Kiểm tra requires_subject_code và requires_grade_code trong response của /hub/metrics/push-config để biết metric nào bắt buộc field nào. Thiếu field bắt buộc sẽ bị reject.

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

HTTP Status	Nguyên nhân	Giải pháp
`400`	`measured_at` trong tương lai	Sử dụng thời gian hiện tại hoặc quá khứ
`400`	Validation error (thiếu field, sai format)	Kiểm tra lại payload theo spec
`401`	API key không hợp lệ	Kiểm tra lại header X-Api-Key
`200` với `rejected > 0`	Metric key không tồn tại (`metric_not_found`)	Gọi lại `/api/v1/lms/hub/metrics/push-config` để lấy danh sách key hợp lệ
`200` với `rejected > 0`	Thiếu `subject_code` (`missing_subject_code`)	Metric có `requires_subject_code: true` nhưng payload thiếu `subject_code`
`200` với `rejected > 0`	Thiếu `grade_code` (`missing_grade_code`)	Metric có `requires_grade_code: true` nhưng payload thiếu `grade_code`