API Push chỉ số trường học (DTI) | QIG LMS Docs

API đẩy chỉ số thống kê cấp trường lên hệ thống DTI. Xem Tổng quan tích hợp DTI để biết thông tin kết nối và cấu hình push.

1. Endpoint

Method: POST
Path: /api/v1/lms/hub/push
Batch: Tối đa 500 trường trong 1 request

2. Request body

{
  "measured_at": "2026-04-14T23:00:00.000Z",
  "schools": [
    {
      "provdoet_code": "01",
      "school_code": "SCHOOL_001",
      "school_level": "03",
      "school_year_code": 2025,
      "semester_code": 1,
      "division_code": "01001001",
      "metrics": [
        { "key": "teacher_accounts", "value": 500 }
      ]
    }
  ]
}

json

3. Mô tả các fields

Top-level fields

Field	Bắt buộc	Type	Mô tả
`measured_at`	Có	string (ISO 8601)	Thời điểm đo dữ liệu. Không được trong tương lai
`schools`	Có	array	Danh sách trường (tối đa 500)

School object

Field	Bắt buộc	Type	Mô tả
`provdoet_code`	Có	string (max 10)	Mã Sở GD&ĐT
`school_code`	Có	string (max 50)	Mã trường
`school_level`	Có	string	`01` Mầm non, `02` Tiểu học, `03` THCS, `04` THPT, `05` GDTX
`school_year_code`	Có	integer	Năm học. VD: `2025`, `2026`
`semester_code`	Có	integer	Học kỳ: `1` hoặc `2`
`division_code`	Không	string (max 20)	Mã xã/phường
`metrics`	Có	array	Danh sách chỉ số

Lưu ý: Bộ 4 giá trị provdoet_code + school_code + school_level + school_year_code xác định duy nhất 1 trường.

Metric item

Field	Bắt buộc	Type	Mô tả
`key`	Có	string	Mã metric (lấy từ push-config)
`value`	Có	number	Giá trị metric
`dim_value`	Có nếu metric có dim_type	string	Giá trị dimension. VD: `mobile`, `video`
`subject_code`	Không	string (tối đa 4 ký tự số)	Mã chương trình môn học. Xem giải thích
`grade_code`	Không	string (2 ký tự số)	Mã khối/lớp. VD: `09` = Khối 9

4. Danh sách chỉ số cấp trường

Key	Tên chỉ số	Đơn vị	dim_value	Tần suất
`teacher_accounts`	Tổng tài khoản GV	accounts	—	1/ngày
`student_accounts`	Tổng tài khoản HS	accounts	—	1/ngày
`total_activated_teachers`	GV đã kích hoạt	accounts	—	1/ngày
`total_activated_students`	HS đã kích hoạt	accounts	—	1/ngày
`active_teachers`	GV đăng nhập trong ngày	accounts	—	1/ngày
`active_students`	HS đăng nhập trong ngày	accounts	—	1/ngày
`online_students`	HS đang trực tuyến	students	—	1/giờ
`online_classes`	Số tiết học online	periods	—	1/ngày
`lesson_completion_rate`	Tỷ lệ HS hoàn thành bài giảng	%	—	1/tuần
`class_participation_rate`	Tỷ lệ tham gia lớp online	%	—	1/ngày
`total_assessments_conducted`	Số lần tổ chức kiểm tra	times	—	1/tuần
`shared_to_hub`	Học liệu chia sẻ lên Trục	resources	—	1/ngày
`teachers_sharing_on_hub`	GV tham gia chia sẻ	accounts	—	1/ngày

5. Response

{
  "data": {
    "total": 36,
    "accepted": 36,
    "rejected": 0,
    "rejected_details": []
  },
  "message": "OK"
}

json

Nếu có metric bị reject:

{
  "data": {
    "total": 37,
    "accepted": 36,
    "rejected": 1,
    "rejected_details": [
      { "school_code": "SCHOOL_001", "key": "invalid_key", "reason": "metric_not_found" }
    ]
  },
  "message": "OK"

json

Các reason có thể trả về:

Reason	Mô tả
`metric_not_found`	Metric key không tồn tại hoặc bị deactivate
`missing_subject_code`	Metric yêu cầu `subject_code` nhưng payload thiếu
`missing_grade_code`	Metric yêu cầu `grade_code` nhưng payload thiếu


## 6. Ví dụ request đầy đủ

```bash
curl -X POST https://dtiapi.vstudy.edu.vn/api/v1/lms/hub/push \
  -H "X-Api-Key: <api-key-don-vi-duoc-cap>" \
  -H "Content-Type: application/json" \
  -d '{
    "measured_at": "2026-04-14T23:00:00.000Z",
    "schools": [
      {
        "provdoet_code": "01",
        "school_code": "SCHOOL_001",
        "school_level": "03",
        "school_year_code": 2025,
        "semester_code": 1,
        "division_code": "01001001",
        "metrics": [
          { "key": "teacher_accounts", "value": 500 },
          { "key": "student_accounts", "value": 4000 },
          { "key": "total_activated_teachers", "value": 380 },
          { "key": "total_activated_students", "value": 3200 },
          { "key": "active_teachers", "value": 320 },
          { "key": "active_students", "value": 2800 },
          { "key": "online_students", "value": 142 },
          { "key": "online_classes", "value": 45 },
          { "key": "lesson_completion_rate", "value": 68.5 },
          { "key": "class_participation_rate", "value": 82.3 },
          { "key": "total_assessments_conducted", "value": 156 },
          { "key": "shared_to_hub", "value": 120 },
          { "key": "teachers_sharing_on_hub", "value": 12 }
        ]
      }
    ]
  }'