API Push thông tin trường học (DTI) | QIG LMS Docs

API đẩy thông tin trạng thái sử dụng LMS và chia sẻ học liệu cho từng 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/schools
Batch: Tối đa 500 trường trong 1 request
Tần suất: Khuyến nghị 1 lần/ngày

2. Phân biệt với push metrics

	Push Metrics (`/hub/push`)	Push Schools (`/hub/push/schools`)
Mục đích	Đẩy chỉ số thống kê (accounts, rates, duration...)	Đẩy thông tin trạng thái trường (có dùng LMS, có chia sẻ học liệu)
Tần suất	Mỗi giờ hoặc mỗi ngày (tùy metric)	1 lần/ngày
Nội dung	Danh sách metrics với key + value	Danh sách trường với has_lms + shared_to_hub

3. Request body

{
  "measured_at": "2026-04-18T00:00:00.000Z",
  "schools": [
    {
      "provdoet_code": "01",
      "school_code": "SCHOOL_001",
      "school_level": "03",
      "school_year_code": 2025,
      "semester_code": 1,
      "division_code": "01001001",
      "has_lms": true,
      "shared_to_hub": true
    },
    {
      "provdoet_code": "01",
      "school_code": "SCHOOL_002",
      "school_level": "04",
      "school_year_code": 2025,
      "semester_code": 1,
      "division_code": "01001002",
      "has_lms": true,
      "shared_to_hub": false
    }
  ]
}

json

4. 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. Hỗ trợ push data quá khứ khi tích hợp lần đầu.
`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` = năm học 2025-2026
`semester_code`	Có	integer	Học kỳ: `1` hoặc `2`
`division_code`	Không	string (max 20)	Mã quận/huyện (phục vụ thống kê theo đơn vị hành chính)
`has_lms`	Có	boolean	Trường có đang sử dụng hệ thống LMS không
`shared_to_hub`	Có	boolean	Trường có chia sẻ học liệu lên Trục không

Lưu ý: Bộ 5 giá trị provdoet_code + school_code + school_level + school_year_code + semester_code xác định duy nhất 1 trường. Nếu trường đã tồn tại, thông tin sẽ được cập nhật.

5. Response

{
  "data": {
    "total": 2,
    "accepted": 2
  },
  "message": "OK"
}

json

6. Lưu ý quan trọng

Push data quá khứ khi tích hợp lần đầu

Khi LMS mới bắt đầu tích hợp, có thể push lại data lịch sử bằng cách gửi nhiều request với measured_at khác nhau:

# Push data tháng 1
curl -X POST .../api/v1/lms/hub/push/schools \
  -H "X-Api-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "measured_at": "2026-01-15T00:00:00.000Z", "schools": [...] }'
 
# Push data tháng 2
curl -X POST .../api/v1/lms/hub/push/schools \
  -H "X-Api-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "measured_at": "2026-02-15T00:00:00.000Z", "schools": [...] }'

bash

Quan trọng: Khi push data quá khứ, nên push theo thứ tự thời gian (tháng 1 trước, tháng 2 sau) để đảm bảo dữ liệu nhất quán.

Trường ngừng sử dụng LMS

Nếu trường ngừng sử dụng LMS, gửi has_lms: false. Hệ thống sẽ cập nhật trạng thái và phản ánh chính xác trên Dashboard (bao gồm tỷ lệ tăng/giảm so với tháng trước).

7. Ví dụ request đầy đủ

curl -X POST https://dtiapi.vstudy.edu.vn/api/v1/lms/hub/push/schools \
  -H "X-Api-Key: <api-key-don-vi-duoc-cap>" \
  -H "Content-Type: application/json" \
  -d '{
    "measured_at": "2026-04-18T00:00:00.000Z",
    "schools": [
      {
        "provdoet_code": "01",
        "school_code": "SCHOOL_001",
        "school_level": "03",
        "school_year_code": 2025,
        "semester_code": 1,
        "division_code": "01001001",
        "has_lms": true,
        "shared_to_hub": true
      },
      {
        "provdoet_code": "01",
        "school_code": "SCHOOL_002",
        "school_level": "04",
        "school_year_code": 2025,
        "semester_code": 1,
        "division_code": "01001002",
        "has_lms": true,
        "shared_to_hub": false
      },
      {
        "provdoet_code": "01",
        "school_code": "SCHOOL_003",
        "school_level": "02",
        "school_year_code": 2025,
        "semester_code": 1,
        "division_code": "01001001",
        "has_lms": false,
        "shared_to_hub": false
      }
    ]
  }'

bash