STAGING
API Reference · Bitrix Inbound Integration

HackKanji AI - Endpoints cho Bitrix

Tài liệu các endpoint HackKanji mở cho hệ thống Bitrix gọi vào (inbound): kéo tổng số chữ đã học của học viên và dữ liệu bài giao của lớp. Tất cả đều là GET, xác thực bằng API key nội bộ (không dùng JWT của người dùng).

Base URL & xác thực

Mọi request đính kèm header API key; thiếu hoặc sai key → 401 Unauthorized.

Base URL (staging)
http://18.136.196.139:8082
API version
v1  (tiền tố /api/v1)
Auth header
X-Bitrix-Api-Key
Key value (staging)
13F4F9A4-FCBC-44F2-9A40-1CCD27C9995E
Content-Type
application/json
Header xác thực gắn vào mọi request
X-Bitrix-Api-Key: 13F4F9A4-FCBC-44F2-9A40-1CCD27C9995E

Quy ước response

Tất cả endpoint trả về cùng một khung ApiResult. Dữ liệu thật nằm trong data.

Khung phản hồi chung
{
  "isSucceeded": true,            // true = thành công, false = có lỗi nghiệp vụ
  "message": "Success",        // "Success" khi OK; mô tả lỗi khi isSucceeded = false
  "data": { ... }            // payload (object hoặc array, tùy endpoint)
}

Lưu ý: HTTP status có thể là 200 OK nhưng isSucceeded = false (ví dụ không tìm thấy bài tập). Luôn kiểm tra field isSucceeded trước khi đọc data.

1 · Tổng số chữ đã học của học viên

Lấy tổng số chữ (Kanji + Bộ thủ) một học viên đã học, kèm userId để dựng deep-link sang Admin Site.

GET /api/v1/kaizen/students/{studentCode}/learned-count

Bitrix định danh học viên bằng mã học viên (studentCode) của hệ thống HR/Kaizen - không cần biết userId nội bộ của HackKanji.

Path parameters

Tham sốKiểuMô tả
studentCodebắt buộcstringMã học viên trong Kaizen/HR, ví dụ TXDB-AG25090723.
Request cURL
curl --location 'http://18.136.196.139:8082/api/v1/kaizen/students/TXDB-AG25090723/learned-count' \
  --header 'X-Bitrix-Api-Key: 13F4F9A4-FCBC-44F2-9A40-1CCD27C9995E'
Response 200 OK
{
  "isSucceeded": true,
  "message": "Success",
  "data": {
    "studentCode": "TXDB-AG25090723",
    "userId": "7941b07d-e116-f111-aebf-005056a58c24",
    "totalLearned": 20
  }
}

2 · Lịch sử bài giao của lớp

Danh sách các bài đã giao cho một lớp, kèm số HV được giao và số HV đã nộp.

GET /api/v1/kaizen/assignments?kaizenClassId={id}

Trả về mảng bài giao của lớp, sắp theo bài mới nhất.

Query parameters

Tham sốKiểuMô tả
kaizenClassIdbắt buộclongID lớp bên Kaizen, ví dụ 16203.
Request cURL
curl --location 'http://18.136.196.139:8082/api/v1/kaizen/assignments?kaizenClassId=16203' \
  --header 'X-Bitrix-Api-Key: 13F4F9A4-FCBC-44F2-9A40-1CCD27C9995E'
Response 200 OK
{
  "isSucceeded": true,
  "message": "Success",
  "data": [
    {
      "id": "dd9d433e-f36b-1410-8a64-005de5f1ca8c",
      "title": "Hán tự N3 - chữ 321~340",
      "startAt": "2026-06-26T09:30:00+00:00",
      "deadlineAt": "2026-06-26T09:33:00+00:00",
      "studentCount": 3,
      "submittedCount": 0
    },
    {
      "id": "dd9c433e-f36b-1410-8a64-005de5f1ca8c",
      "title": "Hán tự N4 - chữ 142~153",
      "startAt": "2026-06-26T09:24:00+00:00",
      "deadlineAt": "2026-06-27T09:24:00+00:00",
      "studentCount": 3,
      "submittedCount": 1
    },
    {
      "id": "a999433e-f36b-1410-8a64-005de5f1ca8c",
      "title": "Hán tự N5 - chữ 1~20",
      "startAt": "2026-06-25T16:55:00+00:00",
      "deadlineAt": "2026-06-27T16:55:00+00:00",
      "studentCount": 3,
      "submittedCount": 1
    }
  ]
}

startAt / deadlineAt theo chuẩn ISO-8601, múi giờ UTC (offset +00:00). Bitrix tự đổi sang giờ VN (UTC+7) khi hiển thị.

3 · Trạng thái từng học viên trong một bài

Ai đã xác nhận làm bài, ai đã nộp - dùng để hiển thị tick xanh / trạng thái.

GET /api/v1/kaizen/assignments/{id}/students

Trả về danh sách HV của bài, mỗi HV có cờ isConfirmed, isSubmitted và submissionStatus.

Path parameters

Tham sốKiểuMô tả
idbắt buộcguidID bài giao (lấy từ endpoint #2, field id).

Giá trị submissionStatus

Assigned - vừa giao, chưa xác nhận Confirmed - đã bấm "Bắt đầu", đang làm Submitted - đã nộp Expired - quá hạn, chưa nộp
Request cURL
curl --location 'http://18.136.196.139:8082/api/v1/kaizen/assignments/dd9d433e-f36b-1410-8a64-005de5f1ca8c/students' \
  --header 'X-Bitrix-Api-Key: 13F4F9A4-FCBC-44F2-9A40-1CCD27C9995E'
Response 200 OK
{
  "isSucceeded": true,
  "message": "Success",
  "data": [
    {
      "studentCode": "TXDB-AG25090723",
      "studentUserId": "7941b07d-e116-f111-aebf-005056a58c24",
      "studentFullName": null,
      "isConfirmed": true,
      "isSubmitted": false,
      "submissionStatus": "Expired"
    },
    {
      "studentCode": null,
      "studentUserId": "1b99f4be-0bab-f011-aeb9-005056a58c24",
      "studentFullName": null,
      "isConfirmed": true,
      "isSubmitted": false,
      "submissionStatus": "Expired"
    },
    {
      "studentCode": null,
      "studentUserId": "916f9e47-bbac-f011-aeb9-005056a58c24",
      "studentFullName": null,
      "isConfirmed": true,
      "isSubmitted": false,
      "submissionStatus": "Expired"
    }
  ]
}

4 · Con số tổng đã học của từng HV trong bài

Số chữ đã học / tổng số chữ được giao của mỗi HV - con số này bấm vào deep-link được sang Admin Site.

GET /api/v1/kaizen/assignments/{id}/summary

Trả về danh sách HV của bài kèm learnedCount (đã học) và totalCount (được giao).

Path parameters

Tham sốKiểuMô tả
idbắt buộcguidID bài giao (lấy từ endpoint #2, field id).
Request cURL
curl --location 'http://18.136.196.139:8082/api/v1/kaizen/assignments/dd9d433e-f36b-1410-8a64-005de5f1ca8c/summary' \
  --header 'X-Bitrix-Api-Key: 13F4F9A4-FCBC-44F2-9A40-1CCD27C9995E'
Response 200 OK
{
  "isSucceeded": true,
  "message": "Success",
  "data": [
    {
      "studentCode": "TXDB-AG25090723",
      "studentUserId": "7941b07d-e116-f111-aebf-005056a58c24",
      "studentFullName": null,
      "learnedCount": 0,
      "totalCount": 20
    },
    {
      "studentCode": null,
      "studentUserId": "1b99f4be-0bab-f011-aeb9-005056a58c24",
      "studentFullName": null,
      "learnedCount": 0,
      "totalCount": 20
    },
    {
      "studentCode": null,
      "studentUserId": "916f9e47-bbac-f011-aeb9-005056a58c24",
      "studentFullName": null,
      "learnedCount": 0,
      "totalCount": 20
    }
  ]
}

Lỗi & mã trạng thái

Hai nhóm lỗi thường gặp: sai/thiếu API key, và lỗi nghiệp vụ (không tìm thấy).

Sai / thiếu API key 401 Unauthorized
{
  "message": "Invalid or missing Bitrix API key."
}
Không tìm thấy dữ liệu 200 OK · isSucceeded=false
{
  "isSucceeded": false,
  "message": "Không tìm thấy bài tập.",
  "data": null
}
HTTP statusÝ nghĩa
200Gọi thành công (vẫn phải kiểm tra isSucceeded để phân biệt lỗi nghiệp vụ).
401Thiếu header X-Bitrix-Api-Key hoặc key sai.
500Lỗi hệ thống phía HackKanji - thử lại hoặc liên hệ team backend.