Tài liệu API & Tích hợp

1. Tổng quan & Xác thực (Authentication)

Base URL:https://kbase.ictu.edu.vn

Header xác thực:X-API-Key: kb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Bắt buộc Role: IT_ADMIN

Liên hệ với người quản lý hệ thống Kbase để được cung cấp API KEY

2. Cơ chế Đồng bộ Tri thức qua Manifest Version

Để tối ưu chi phí tính toán Vector Embedding và tránh lãng phí băng thông mạng, Chatbot so sánh mã băm summary.knowledge_root_hash với phiên bản đang lưu cục bộ:

Trùng khớp (IN_SYNC)

root_hash == saved_hash: Kho tri thức của Chatbot đã ở bản mới nhất 100%. Dừng phiên đồng bộ ngay, không tải thêm gì.

Lệch mã (OUT_OF_SYNC)

root_hash != saved_hash: Đọc mảng revoked_documents để xóa khỏi Vector DB, đọc ready_for_chatbot để kéo Markdown mới và cập nhật doc_relations.

Lệnh cURL kiểm tra nhanh Version Hash:

bash

curl -s "https://kbase.ictu.edu.vn/api/v1/documents/manifest" \
  -H "X-API-Key: YOUR_IT_ADMIN_KEY" | jq '.summary.knowledge_root_hash'

3. Bảng tổng hợp Danh mục Endpoints Trả về cho Chatbot

Method	Endpoint	Dữ liệu trả về & Mục đích	Chi tiết
GET	/api/v1/documents/manifest	Bản kê đồng bộ (Sync Manifest) & Version Hash toàn cục	Xem ↓
GET	/api/v1/documents/{id}/markdown	Nội dung tài liệu đang phát hành (Core RAG)	Xem ↓
GET	/api/v1/documents/{id}/file	Tệp nguyên bản đối chiếu (`?download=true`)	Xem ↓
GET	/api/v1/documents/relations	Mạng lưới quan hệ hiệu lực (sửa đổi, thay thế, bãi bỏ)	Xem ↓
GET	/api/v1/faqs/export-jsonl	Kho câu hỏi FAQ xuất trọn gói JSON Lines	Xem ↓
GET	/api/v1/documents/formatter-spec	Spec quy chuẩn cấu trúc Markdown và YAML Schema	Xem ↓

GET/api/v1/documents/manifest

Bản kê Đồng bộ & Version Hash

Trả về Point-in-time Snapshot chứa mã root hash toàn cục, danh sách tài liệu sẵn sàng làm knowledge (ready_for_chatbot), văn bản bị bãi bỏ/thu hồi (revoked_documents) và toàn bộ quan hệ hiệu lực.

Tham số yêu cầu

Tham số	Vị trí	Kiểu	Mô tả
X-API-Key*	header	string	Khóa API có vai trò IT_ADMIN.

Ví dụ Request (cURL)

bash

curl -X GET "https://kbase.ictu.edu.vn/api/v1/documents/manifest" \
  -H "X-API-Key: kb_live_your_key_here"

Phản hồi mẫu (200 OK)application/json

json

{
  "manifest_version": "1.2.0",
  "generated_at": "2026-09-07T03:30:00+00:00",
  "summary": {
    "snapshot_id": "snap_1788748194_c3c41882",
    "knowledge_root_hash": "sha256:c3c418823a64019a86bc485890d981ba6602058e1c667086e3954593922d99d3",
    "total_ready_for_chatbot_documents": 144,
    "total_revoked_documents": 25,
    "total_doc_relations": 699,
    "total_enabled_faqs": 729
  },
  "ready_for_chatbot": [
    {
      "id": "b83bd45d-edbc-4537-a678-d1f463f47793",
      "document_number": "1196/QĐ-ĐHCNTT&TT",
      "title": "Quy định cấp phát văn bằng, chứng chỉ",
      "content_hash": "sha256:192ffd82f...",
      "markdown_api_url": "/api/v1/documents/b83bd45d-edbc-4537-a678-d1f463f47793/markdown",
      "original_file_url": "/api/v1/documents/b83bd45d-edbc-4537-a678-d1f463f47793/file?download=true"
    }
  ],
  "revoked_documents": [
    {
      "id": "786e167b-35ee-4036-91b2-b7aa77f5932a",
      "document_number": "51/QĐ-ĐHCNTT&TT",
      "title": "Quy định học bổng cũ",
      "reason": "REPLACED",
      "replaced_by": [
        { "id": "2da12b9d...", "document_number": "488/QĐ-ĐHCNTT&TT", "title": "Quy định học bổng mới 2024" }
      ]
    }
  ]
}

GET/api/v1/documents/{id}/markdown

Nội dung Markdown Đang phát hành (Core RAG)

Trả về nội dung văn bản ở định dạng Markdown sạch, đã được xử lý OCR và chuẩn hóa cấu trúc theo YAML frontmatter. Sẵn sàng nạp vào Vector DB.

Tham số yêu cầu

Tham số	Vị trí	Kiểu	Mô tả
id*	path	string (UUID)	ID định danh tài liệu.
X-API-Key*	header	string	Khóa API có vai trò IT_ADMIN.

Ví dụ Request (cURL)

bash

curl -X GET "https://kbase.ictu.edu.vn/api/v1/documents/b83bd45d-edbc-4537-a678-d1f463f47793/markdown" \
  -H "X-API-Key: kb_live_your_key_here"

Phản hồi mẫu (200 OK)application/json

json

{
  "id": "b83bd45d-edbc-4537-a678-d1f463f47793",
  "document_number": "1196/QĐ-ĐHCNTT&TT",
  "title": "Quyết định ban hành Quy định về cấp phát văn bằng, chứng chỉ",
  "status": "PUBLISHED",
  "content_hash": "sha256:192ffd82f0c51f4fd1adcda2f6fb204bb455a378b2b8f07a1a62a61fa97780b6",
  "markdown_content": "---\ntitle: Quy định cấp phát văn bằng...\n---\n\n# CHƯƠNG I: QUY ĐỊNH CHUNG\n\n## Điều 1. Phạm vi điều chỉnh...\n",
  "updated_at": "2026-09-07T02:29:54+00:00"
}

GET/api/v1/documents/{id}/file

Tải tệp Tài liệu gốc (Original Document)

Trả về file nguyên bản (PDF, DOCX, XLSX...) đính kèm dấu đỏ, chữ ký để Chatbot cung cấp link tải đối chiếu cho người dùng cuối khi trả lời câu hỏi.

Tham số yêu cầu

Tham số	Vị trí	Kiểu	Mô tả
id*	path	string (UUID)	ID định danh tài liệu.
download	query	boolean	Gán true để nhận Header Content-Disposition attachment tải về máy.
X-API-Key*	header	string	Khóa API có vai trò IT_ADMIN.

Ví dụ Request (cURL)

bash

curl -O -J -L "https://kbase.ictu.edu.vn/api/v1/documents/b83bd45d-edbc-4537-a678-d1f463f47793/file?download=true" \
  -H "X-API-Key: kb_live_your_key_here"

Phản hồi mẫu (200 OK)application/pdf | application/vnd...

json

// Trả về luồng nhị phân (Binary Stream) với Header:
// Content-Type: application/pdf
// Content-Disposition: attachment; filename="QD 1196 CAP PHAT VAN BANG.pdf"

GET/api/v1/documents/relations

Mạng lưới Quan hệ Văn bản (doc_relations)

Cung cấp bản đồ quan hệ hiệu lực pháp lý (amends: sửa đổi, replaces: thay thế, annuls: bãi bỏ, guides: hướng dẫn) giữa các văn bản trong trường.

Tham số yêu cầu

Tham số	Vị trí	Kiểu	Mô tả
X-API-Key*	header	string	Khóa API có vai trò IT_ADMIN.

Ví dụ Request (cURL)

bash

curl -X GET "https://kbase.ictu.edu.vn/api/v1/documents/relations" \
  -H "X-API-Key: kb_live_your_key_here"

Phản hồi mẫu (200 OK)application/json

json

{
  "total_relations": 699,
  "relations": [
    {
      "id": "rel_68f6b4ef",
      "source_doc_id": "13cd2bde-ad0b-42b1-96d9-1f6e99e821b4",
      "source_doc_number": "1503/QĐ-ĐHCNTT&TT",
      "target_doc_id": "b83bd45d-edbc-4537-a678-d1f463f47793",
      "target_doc_number": "515/QĐ-ĐHCNTT&TT",
      "target_doc_title": "Quy định về công tác đào tạo đại học",
      "relation_type": "amends",
      "relation_label": "Sửa đổi, bổ sung",
      "target_scope": ["Điều 8", "Điều 12"],
      "is_internal": true
    }
  ]
}

GET/api/v1/faqs/export-jsonl

Xuất trọn gói Kho câu hỏi FAQ

Xuất toàn bộ các cặp câu hỏi - câu trả lời FAQ đã duyệt sang định dạng JSON Lines (JSONL). Tệp nhẹ (< 250 KB), tải nhanh dưới 1 giây để nạp đè vào cơ sở dữ liệu.

Tham số yêu cầu

Tham số	Vị trí	Kiểu	Mô tả
X-API-Key*	header	string	Khóa API có vai trò IT_ADMIN.

Ví dụ Request (cURL)

bash

curl -X GET "https://kbase.ictu.edu.vn/api/v1/faqs/export-jsonl" \
  -H "X-API-Key: kb_live_your_key_here" -o faqs.jsonl

Phản hồi mẫu (200 OK)application/x-ndjson

json

{"id": "faq_1", "question": "Sinh viên cần đạt bao nhiêu tín chỉ để xét tốt nghiệp?", "answer": "Theo quy chế đào tạo...", "department": "Phòng đào tạo", "category": "Tốt nghiệp"}
{"id": "faq_2", "question": "Hạn nộp hồ sơ xét học bổng kỳ 1 là ngày nào?", "answer": "Thời hạn nộp là trước 17h ngày 15/10...", "department": "Phòng công tác người học", "category": "Học bổng"}

GET/api/v1/documents/formatter-spec

Quy chuẩn Formatter YAML Spec

Tải tài liệu schema YAML quy định cấu trúc 3 cấp Header và chuẩn định dạng Markdown của KBase để cấu hình bộ phân mảnh (chunker) cho RAG.

Tham số yêu cầu

Tham số	Vị trí	Kiểu	Mô tả
X-API-Key*	header	string	Khóa API có vai trò IT_ADMIN.

Ví dụ Request (cURL)

bash

curl -X GET "https://kbase.ictu.edu.vn/api/v1/documents/formatter-spec" \
  -H "X-API-Key: kb_live_your_key_here" -o knowledge-format.yaml

Phản hồi mẫu (200 OK)application/yaml

json

version: "1.0.0"
document_structure:
  frontmatter:
    required: ["title", "document_number", "department", "issued_date"]
  body:
    heading_hierarchy:
      h1: "Phần / Chương"
      h2: "Mục / Điều"
      h3: "Khoản"

10. Giới hạn Tần suất & Quy chuẩn Xử lý Lỗi (Errors & Limits)

Giới hạn tần suất gọi (Rate Limit)

Hệ thống giới hạn tối đa 120 requests/phút cho mỗi API Key. Khi vượt ngưỡng, server phản hồi mã HTTP 429 Too Many Requests kèm header Retry-After: <số_giây>. Client cần chờ đúng thời gian quy định trước khi gọi lại.

Thời gian phản hồi cam kết (Timeout SLA)

Manifest & Relations API: < 10 giây.
Markdown API: < 15 giây.
File Download & FAQ Export: < 30 giây.

Định dạng phản hồi lỗi chuẩn (JSON Error Response):

json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Quá giới hạn 120 requests/phút. Vui lòng thử lại sau.",
    "details": {
      "retry_after_seconds": 30
    }
  }
}