Kết nối LMS với Learnify Live

API v1 · JSON · Thời gian ISO 8601 có timezone · Phân trang 50 mục.

API key chỉ dùng từ backend. LMS xác thực người dùng, kiểm tra quyền khóa học và xác định vai trò trước khi yêu cầu vé vào lớp. Hub giới hạn key theo tenant; không dùng key tenant trong trình duyệt.

1. Tạo và theo dõi buổi học

POST /api/v1/meetings
X-Api-Key: <private key>
Content-Type: application/json

{
  "externalId": "course-58-session-01",
  "title": "Buổi học 01",
  "description": "Nội dung buổi học",
  "start": "2026-11-12T08:00:00+07:00",
  "durationMinutes": 90,
  "capacity": 100,
  "autoRecord": true
}

HTTP 202: đã giữ chỗ, đang tạo phòng. Lưu id trả về. Gọi GET /api/v1/meetings/{id} cho đến khi trạng thái scheduled. Cùng externalId và payload trả về cùng buổi; payload khác nhận 409. Không đổi externalId để thử lại sau timeout.

GET /api/v1/meetings?from=…&to=…&page=1 lấy lịch giao với khoảng thời gian. PUT /api/v1/meetings/{id} gửi payload lịch mới với externalId giữ nguyên. POST …/{id}/cancel hủy; POST …/{id}/end kết thúc. Thao tác đồng bộ chạy nền; đọc lại trạng thái để xác nhận.

2. Cấp vé vào lớp

POST /api/v1/meetings/{id}/launch
X-Api-Key: <private key>

{
  "subject": "learner-123",
  "displayName": "Tên người học",
  "host": false,
  "returnUrl": "https://lms.example.edu/lich-hoc"
}

→ { "url": "/room#<single-use-ticket>", "expiresIn": 120 }

Chuyển người dùng đến origin của hub cộng URL tương đối. Vé có hiệu lực 2 phút, dùng một lần; fragment không đi vào access log. Chỉ server LMS được cấp host: true cho giảng viên có quyền. Hub không gửi ZAK qua URL. Return URL cần HTTPS thuộc origin đã khai báo.

3. Điểm danh và bản ghi

GET /api/v1/meetings/{id}/attendance
GET /api/v1/meetings/{id}/attendance.csv
GET /api/v1/recordings?meetingId={id}
POST /api/v1/meetings/{id}/reconcile

Điểm danh có participants (thời gian hợp các khoảng tham gia, không cộng trùng thiết bị) và segments để truy vết. Khoảng thiếu sự kiện ra lớp được đánh dấu incomplete. Subject chỉ có khi định danh provider khớp vé đã dùng; không suy đoán từ tên. LMS tự áp dụng quy tắc chuyên cần.

Bản ghi chỉ dùng khi state=ready. Quyền xem Drive tùy cấu hình tổ chức. Không dùng URL tải tạm Zoom làm URL học liệu lâu dài.

4. Nhận sự kiện

Quản trị viên khai báo callback HTTPS cùng origin LMS và cấp callback secret. Hub gửi JSON có version, meetingId, externalId, type và thời gian.

X-Live-Event: <stable-delivery-id>
X-Live-Timestamp: <unix-seconds>
X-Live-Signature: <hex-hmac-sha256>

signature = HMAC_SHA256(secret, timestamp + "." + raw_body)

Xác minh chữ ký bằng so sánh hằng thời gian, timestamp trong 5 phút. Lưu mã sự kiện trong transaction với dữ liệu đồng bộ để chống lặp; trả 2xx khi đã lưu bền vững. Hub retry theo backoff, tối đa 8 lần trước khi chờ quản trị viên. Callback là tín hiệu để LMS đọc lại dữ liệu chuẩn từ API, không phải lệnh tự chốt điểm.

5. Trạng thái và lỗi

provisioning → scheduled → live → ended; hủy qua canceling → canceled. reconcile giữ chỗ khi kết quả provider chưa rõ, không tạo lại mù. 400 dữ liệu không hợp lệ; 401 chưa xác thực; 403 không có quyền; 404 không có dữ liệu trong phạm vi; 409 xung đột; 502/503 provider/cấu hình chưa sẵn sàng.

← Về không gian quản trị