Học viện hàng hóa — API cho bên thứ ba

Tổng cộng 7 endpoint: 1 health check (không cần key) và 6 endpoint nội dung. Mỗi endpoint có khối test riêng, dùng Base URL / key ở khối Cấu hình test.

1.1 · Health check

Kiểm tra service. Không cần API key — hữu ích cho monitor và cho việc phát hiện nội dung vừa đổi (§7). Endpoint này không đi qua cache và không có ETag.

curl https://hvhh.sfi.com.vn/api/health

Response

{ "ok": true, "service": "sfi-hvhh", "contentVersion": 7 }

1.2 · Danh sách khóa học

Danh sách toàn bộ khóa học đã đăng, đã sắp thứ tự. Đây là endpoint vào của cây nội dung — dùng cho trang danh sách khóa học.

Response 200

{
  "data": [
    {
      "id": "clx7k2h9d9000abcd1234efgh",
      "slug": "giao-dich-hang-hoa-phai-sinh-co-ban",
      "title": "Giao dịch hàng hóa phái sinh cơ bản",
      "description": "Khóa học nền tảng về giao dịch hàng hóa phái sinh.",
      "coverImageUrl": "https://cdn.example.com/hvhh/khoa-hoc-1.jpg",
      "sortOrder": 0,
      "topicCount": 2,
      "hasEndQuiz": true,
      "topics": [
        {
          "id": "clx7k2h9d0000abcd1234efgh",
          "slug": "gioi-thieu-hang-hoa",
          "title": "Giới thiệu hàng hóa",
          "description": "Kiến thức nền tảng về thị trường hàng hóa phái sinh.",
          "coverImageUrl": "https://cdn.example.com/hvhh/anh-bia.jpg",
          "sortOrder": 0,
          "lessonCount": 1,
          "hasEndQuiz": true,
          "lessons": [
            {
              "id": "clx7k2h9d0001abcd1234efgh",
              "slug": "hop-dong-tuong-lai-la-gi",
              "title": "Hợp đồng tương lai là gì?",
              "coverImageUrl": "https://cdn.example.com/hvhh/bai-1.jpg",
              "sortOrder": 0,
              "updatedAt": "2026-08-21T07:30:00.000Z"
            }
          ],
          "updatedAt": "2026-08-21T07:30:00.000Z"
        }
      ],
      "updatedAt": "2026-08-22T07:30:00.000Z"
    }
  ],
  "total": 1
}

Field cấp ngoài

Mỗi phần tử trong data — đối tượng CourseSummary

1.3 · Chi tiết một khóa học

Mục lục một khóa học: danh sách chủ đề kèm danh sách bài học của từng chủ đề, cộng quiz cuối khóa.

Tham số đường dẫn

Response 200

{
  "id": "clx7k2h9d9000abcd1234efgh",
  "slug": "giao-dich-hang-hoa-phai-sinh-co-ban",
  "title": "Giao dịch hàng hóa phái sinh cơ bản",
  "description": "Khóa học nền tảng về giao dịch hàng hóa phái sinh.",
  "coverImageUrl": "https://cdn.example.com/hvhh/khoa-hoc-1.jpg",
  "sortOrder": 0,
  "updatedAt": "2026-08-22T07:30:00.000Z",
  "topics": [
    {
      "id": "clx7k2h9d0000abcd1234efgh",
      "slug": "gioi-thieu-hang-hoa",
      "title": "Giới thiệu hàng hóa",
      "description": "Kiến thức nền tảng về thị trường hàng hóa phái sinh.",
      "coverImageUrl": "https://cdn.example.com/hvhh/anh-bia.jpg",
      "sortOrder": 0,
      "lessonCount": 1,
      "hasEndQuiz": true,
      "lessons": [
        {
          "id": "clx7k2h9d0001abcd1234efgh",
          "slug": "hop-dong-tuong-lai-la-gi",
          "title": "Hợp đồng tương lai là gì?",
          "coverImageUrl": "https://cdn.example.com/hvhh/bai-1.jpg",
          "sortOrder": 0,
          "updatedAt": "2026-08-21T07:30:00.000Z"
        }
      ],
      "updatedAt": "2026-08-21T07:30:00.000Z"
    }
  ],
  "endQuiz": {
    "questions": [
      {
        "id": "clx7k2h9d9005abcd1234efgh",
        "type": "multiple_choice",
        "question": "Chọn các phát biểu đúng về giao dịch hàng hóa phái sinh:",
        "explanation": null,
        "options": [
          { "id": "clx7k2h9d9006abcd1234efgh", "text": "Phát biểu A", "isCorrect": true },
          { "id": "clx7k2h9d9007abcd1234efgh", "text": "Phát biểu B", "isCorrect": false }
        ]
      }
    ]
  }
}

Field cấp khóa học

Mỗi phần tử topics[] — đối tượng CourseTopic

1.4 · Chi tiết một chủ đề

Toàn bộ nội dung một chủ đề trong một request: tất cả bài học kèm HTML và quiz, cộng quiz cuối chủ đề. Đây là endpoint nên dùng để tải một khoá học.

Tham số đường dẫn

Response 200

{
  "id": "clx7k2h9d0000abcd1234efgh",
  "course": {
    "id": "clx7k2h9d9000abcd1234efgh",
    "slug": "giao-dich-hang-hoa-phai-sinh-co-ban",
    "title": "Giao dịch hàng hóa phái sinh cơ bản"
  },
  "slug": "gioi-thieu-hang-hoa",
  "title": "Giới thiệu hàng hóa",
  "description": "Kiến thức nền tảng về thị trường hàng hóa phái sinh.",
  "coverImageUrl": "https://cdn.example.com/hvhh/anh-bia.jpg",
  "sortOrder": 0,
  "updatedAt": "2026-08-21T07:30:00.000Z",
  "lessons": [
    {
      "id": "clx7k2h9d0001abcd1234efgh",
      "slug": "hop-dong-tuong-lai-la-gi",
      "title": "Hợp đồng tương lai là gì?",
      "coverImageUrl": "https://cdn.example.com/hvhh/bai-1.jpg",
      "sortOrder": 0,
      "contentHtml": "<h2>Khái niệm</h2><p>Hợp đồng tương lai là…</p>",
      "quizzes": [
        {
          "id": "clx7k2h9d0002abcd1234efgh",
          "type": "single_choice",
          "question": "Hợp đồng tương lai là gì?",
          "explanation": "Xem lại phần Khái niệm.",
          "options": [
            { "id": "clx7k2h9d0003abcd1234efgh", "text": "Một thoả thuận mua/bán trong tương lai", "isCorrect": true },
            { "id": "clx7k2h9d0004abcd1234efgh", "text": "Một loại cổ phiếu", "isCorrect": false }
          ]
        }
      ],
      "updatedAt": "2026-08-21T07:30:00.000Z"
    }
  ],
  "endQuiz": {
    "questions": [
      {
        "id": "clx7k2h9d0005abcd1234efgh",
        "type": "multiple_choice",
        "question": "Chọn các phát biểu đúng:",
        "explanation": null,
        "options": [
          { "id": "clx7k2h9d0006abcd1234efgh", "text": "Phát biểu A", "isCorrect": true },
          { "id": "clx7k2h9d0007abcd1234efgh", "text": "Phát biểu B", "isCorrect": true },
          { "id": "clx7k2h9d0008abcd1234efgh", "text": "Phát biểu C", "isCorrect": false }
        ]
      }
    ]
  }
}

Field cấp chủ đề

Mỗi phần tử lessons[] — đối tượng Lesson

Bài học không có field description; phần dẫn nhập nằm trong contentHtml.

1.5 · Chi tiết một bài học

Một bài học đơn lẻ. Dùng khi người học mở sâu vào một bài (deep link) và bạn không muốn tải cả chủ đề.

Tham số đường dẫn

Response 200

{
  "id": "clx7k2h9d0001abcd1234efgh",
  "slug": "hop-dong-tuong-lai-la-gi",
  "title": "Hợp đồng tương lai là gì?",
  "coverImageUrl": "https://cdn.example.com/hvhh/bai-1.jpg",
  "sortOrder": 0,
  "contentHtml": "<h2>Khái niệm</h2><p>Hợp đồng tương lai là…</p>",
  "topic": {
    "id": "clx7k2h9d0000abcd1234efgh",
    "slug": "gioi-thieu-hang-hoa",
    "title": "Giới thiệu hàng hóa",
    "course": {
      "id": "clx7k2h9d9000abcd1234efgh",
      "slug": "giao-dich-hang-hoa-phai-sinh-co-ban",
      "title": "Giao dịch hàng hóa phái sinh cơ bản"
    }
  },
  "quizzes": [ … giống lessons[].quizzes ở §1.4 … ],
  "updatedAt": "2026-08-21T07:30:00.000Z"
}

Các field id, slug, title, coverImageUrl, sortOrder, contentHtml, quizzes, updatedAt giống hệt Lesson ở §1.4. Khác biệt duy nhất: có thêm topic — thông tin tối thiểu về chủ đề cha và khóa học của nó, đủ để vẽ trọn breadcrumb Khóa học → Chủ đề → Bài học mà không phải gọi thêm request.

1.6 · Danh sách thử thách

Danh sách toàn bộ thử thách đã đăng, đã sắp thứ tự. Thử thách là một bộ câu hỏi độc lập: không thuộc khóa học hay chủ đề nào, không có bài học — chỉ có câu hỏi. Dùng cho màn hình "chọn thử thách" tách khỏi phần khóa học.

Response 200

{
  "data": [
    {
      "id": "clx9m1a2b0000abcd1234efgh",
      "slug": "thu-thach-kien-thuc-hang-hoa",
      "title": "Thử thách kiến thức hàng hóa",
      "description": "Bộ câu hỏi tổng hợp toàn bộ kiến thức nền tảng.",
      "coverImageUrl": "https://cdn.example.com/hvhh/thu-thach-1.jpg",
      "sortOrder": 0,
      "questionCount": 50,
      "updatedAt": "2026-09-15T07:30:00.000Z"
    }
  ],
  "total": 1
}

Field cấp ngoài

Mỗi phần tử trong data — đối tượng ChallengeSummary

1.7 · Bộ câu hỏi của một thử thách

Bộ câu hỏi của một thử thách. Đây là endpoint duy nhất của API có tham số query — mọi endpoint khác bỏ qua query string hoàn toàn.

Tham số đường dẫn

Tham số query

# Toàn bộ bộ câu hỏi, đúng thứ tự đã soạn
curl -H "X-API-Key: hvhh_xxxxxxxx" \
  "https://hvhh.sfi.com.vn/api/v1/challenges/thu-thach-kien-thuc-hang-hoa"

# Bốc ngẫu nhiên 10 câu cho một lượt chơi
curl -H "X-API-Key: hvhh_xxxxxxxx" \
  "https://hvhh.sfi.com.vn/api/v1/challenges/thu-thach-kien-thuc-hang-hoa?mode=random&limit=10"

Response 200

{
  "id": "clx9m1a2b0000abcd1234efgh",
  "slug": "thu-thach-kien-thuc-hang-hoa",
  "title": "Thử thách kiến thức hàng hóa",
  "description": "Bộ câu hỏi tổng hợp toàn bộ kiến thức nền tảng.",
  "coverImageUrl": "https://cdn.example.com/hvhh/thu-thach-1.jpg",
  "sortOrder": 0,
  "updatedAt": "2026-09-15T07:30:00.000Z",
  "mode": "random",
  "totalQuestions": 50,
  "returnedQuestions": 10,
  "questions": [
    {
      "id": "clx9m1a2b0001abcd1234efgh",
      "type": "single_choice",
      "question": "Ký quỹ ban đầu là gì?",
      "explanation": "Xem lại phần Ký quỹ.",
      "options": [
        { "id": "clx9m1a2b0002abcd1234efgh", "text": "Khoản đặt cọc để mở vị thế", "isCorrect": true },
        { "id": "clx9m1a2b0003abcd1234efgh", "text": "Phí giao dịch", "isCorrect": false }
      ]
    }
  ]
}

Các field id, slug, title, description, coverImageUrl, sortOrder, updatedAt giống hệt ChallengeSummary ở §1.6. Bốn field còn lại:

Dùng ở cả năm chỗ: lessons[].quizzes[], endQuiz.questions[] của chủ đề, endQuiz.questions[] của khóa học, quizzes[] của endpoint bài học, và questions[] của thử thách (§1.7). Cấu trúc hoàn toàn giống nhau ở cả năm chỗ — viết một hàm render dùng chung là đủ.

Quiz — một câu hỏi

QuizOption — một lựa chọn

QuizOption không trả sortOrder (thứ tự mảng đã là thứ tự đúng) và không trả quizId (đã nằm lồng trong quiz).

contentHtml là HTML nội dung bài học, đã được làm sạch (sanitize) ở máy chủ trước khi lưu — vì nội dung này phân phối cho nhiều bên thứ ba, việc làm sạch được thực hiện một lần ở nguồn thay vì tin rằng mọi bên tiêu thụ đều tự làm sạch. Đây là allowlist: bất cứ thứ gì không có trong danh sách dưới đây đã bị loại bỏ, nên bạn biết chắc chuỗi này không bao giờ chứa <script>, <style>, <form>, onclick, javascript: hay data: URI.

Thẻ có thể xuất hiện

Thuộc tính có thể xuất hiện

Host được phép trong iframe src

www.youtube.com · youtube.com · www.youtube-nocookie.com · youtube-nocookie.com · player.vimeo.com

Mọi host khác đã bị loại bỏ từ lúc lưu, nên bạn có thể render iframe mà không cần kiểm tra lại host. iframe bắt buộc https, không cho phép URL tương đối.

Thuộc tính CSS được phép trong style

Các data-* (data-width, data-align, data-video-type) là siêu dữ liệu của trình soạn thảo. Bố cục thật đã nằm trong style inline, nên bạn có thể bỏ qua data-* — hoặc dùng data-align nếu muốn tự áp CSS thay vì dựa vào inline style.

CSS tối thiểu để render tử tế

HTML này không kèm class nào, nên nó thừa hưởng CSS của trang bạn. Nếu trang dùng Tailwind Preflight (hoặc bất kỳ CSS reset nào), h2/ul/table sẽ mất hết định dạng mặc định. Hãy bọc nội dung trong một container và áp style cho các thẻ con — đây chính là CSS mà khối "Xem trước nội dung" ở §1.4 / §1.5 đang dùng:

.hvhh-content { line-height: 1.7; }
.hvhh-content h1 { font-size: 1.5rem;  font-weight: 700; margin: 1.5em 0 .5em; }
.hvhh-content h2 { font-size: 1.25rem; font-weight: 700; margin: 1.5em 0 .5em; }
.hvhh-content h3 { font-size: 1.1rem;  font-weight: 600; margin: 1.25em 0 .5em; }
.hvhh-content p  { margin: .75em 0; }
.hvhh-content ul { list-style: disc;    padding-left: 1.5rem; margin: .75em 0; }
.hvhh-content ol { list-style: decimal; padding-left: 1.5rem; margin: .75em 0; }
.hvhh-content a  { color: #e00303; text-decoration: underline; }
.hvhh-content blockquote { border-left: 3px solid #e5e7eb; padding-left: 1rem; color: #475569; }
.hvhh-content pre  { background: #f1f5f9; padding: .75rem; border-radius: .5rem; overflow-x: auto; }
.hvhh-content code { font-family: ui-monospace, monospace; font-size: .9em; }

/* Media: chặn tràn khung trên mobile — inline style có thể đặt width cố định bằng px */
.hvhh-content :is(img, video, iframe) { max-width: 100%; height: auto; }
.hvhh-content iframe { aspect-ratio: 16 / 9; width: 100%; border: 0; }

/* Bảng: nội dung có bảng rộng, đừng để nó đẩy giãn cả trang */
.hvhh-content table { border-collapse: collapse; width: 100%; }
.hvhh-content :is(td, th) { border: 1px solid #e2e8f0; padding: .5rem; }

Bảng rộng nên bọc thêm một div có overflow-x: auto. Nếu dùng Tailwind Typography thì class="prose max-w-none" xử lý hầu hết phần trên, chỉ cần thêm quy tắc cho iframe.

Nếu vẫn muốn sanitize lại ở phía mình

Chính đáng — phòng thủ nhiều tầng. Nhưng cấu hình mặc định của DOMPurify loại bỏ <iframe>, nên video YouTube/Vimeo trong bài học sẽ biến mất. Hãy khai báo tường minh:

import DOMPurify from 'dompurify'

const html = DOMPurify.sanitize(lesson.contentHtml, {
  ADD_TAGS: ['iframe'],
  ADD_ATTR: ['allow', 'allowfullscreen', 'target', 'colwidth',
             'data-width', 'data-align', 'data-video-type'],
})

Đáp án đúng (isCorrect) nằm ngay trong response, theo đúng thiết kế: bên thứ ba tự chấm điểm mà không cần thêm endpoint nào.

/**
 * @param quiz     một đối tượng Quiz từ API
 * @param selected mảng id lựa chọn người học đã chọn
 */
function isAnswerCorrect(quiz, selected) {
  const correct = quiz.options.filter((o) => o.isCorrect).map((o) => o.id)
  const picked = [...new Set(selected)]

  if (quiz.type === 'single_choice') {
    // Đúng một đáp án đúng, và người học chỉ được chọn một.
    return picked.length === 1 && correct.includes(picked[0])
  }
  // multiple_choice: phải chọn đủ và không chọn thừa.
  return picked.length === correct.length && correct.every((id) => picked.includes(id))
}

Quy ước cần thống nhất trước khi làm giao diện:

• single_choice luôn có đúng một isCorrect: true (bảo đảm từ phía SFI khi tạo nội dung).
• multiple_choice có từ một isCorrect: true trở lên — không nhất thiết phải ≥ 2.
• Không có điểm từng phần trong dữ liệu. Muốn chấm nửa điểm cho câu chọn đúng một phần thì đó là quy tắc phía bạn tự định nghĩa.
• Không có "điểm đạt" (passingScore) trong dữ liệu. Ngưỡng đạt do phía bạn quyết định.

Mọi lỗi của /api/v1/* trả JSON dạng { "error": "<thông báo tiếng Việt>", "code": "<mã ổn định>" }. Hãy dựa vào code để phân nhánh xử lý; error là câu tiếng Việt có thể đổi cách diễn đạt.

Không có mã lỗi nào cho rate limit (429) vì hiện chưa có giới hạn tần suất.

API không có webhook và không có endpoint "cái gì đã đổi từ lúc X". Ba cách, từ nhẹ tới nặng:

Mẫu đồng bộ gợi ý cho một hệ thống có máy chủ riêng

1. Mỗi 1–5 phút gọi GET /api/health. Nếu contentVersion khác lần trước → sang bước 2.
2. Gọi GET /api/v1/courses (kèm If-None-Match), rồi từng GET /api/v1/courses/{slug} để lấy mục lục + quiz cuối khóa, rồi từng GET /api/v1/topics/{slug} (kèm If-None-Match riêng cho từng slug) để lấy nội dung thật. Chỉ những endpoint trả 200 mới cần ghi lại.
3. Nếu có dùng thử thách: gọi thêm GET /api/v1/challenges rồi từng GET /api/v1/challenges/{slug} ở mode=full (kèm If-None-Match) — mode=random không có ETag nên không dùng để đồng bộ được.
4. Slug từng có nhưng nay mất khỏi danh sách → đánh dấu ẩn ở phía bạn (đừng xoá hẳn nếu còn dữ liệu tiến độ người học tham chiếu tới nó).

Vì mặc định Cache-Control: max-age=0, must-revalidate, poll thường xuyên không tạo tải đáng kể ở phía Học viện hàng hóa (đã có cache ở máy chủ) — nhưng vẫn tốn một round-trip mạng, nên đừng poll mỗi giây.

Nói rõ để bạn không mất thời gian đi tìm:

• Không phân trang, không lọc, không tìm kiếm, không sắp xếp theo tham số. Danh sách trả về toàn bộ; lọc/tìm kiếm làm ở phía bạn. Hai tham số mode / limit ở §1.7 chỉ để bốc ngẫu nhiên câu hỏi của một thử thách, không phải phân trang — không có con trỏ để lấy "trang sau".
• Không có endpoint danh sách phẳng. Không có danh sách chủ đề hay bài học độc lập với khóa học — muốn toàn bộ cây thì lặp qua /api/v1/courses → /api/v1/courses/{slug} → /api/v1/topics/{slug}.
• Không có endpoint quiz riêng. Quiz chỉ đến kèm bài học, chủ đề, khóa học hoặc thử thách — câu hỏi của thử thách luôn đến theo cả bộ (§1.7).
• Không có endpoint thư viện media. Bên thứ ba chỉ thấy các URL đã nhúng trong contentHtml / coverImageUrl.
• Không ghi. Không tạo/sửa/xoá nội dung, không gửi kết quả làm bài lên hệ thống.
• Không lưu tiến độ hay điểm của người học. Học viện hàng hóa không biết người học là ai; tiến độ, điểm số, chứng chỉ do phía bạn lưu (khoá theo id của khóa học/chủ đề/bài học/quiz).
• Không có nội dung draft. Không có tham số nào để xem bản nháp.
• Không đa ngôn ngữ. Nội dung chỉ tiếng Việt, không có field locale.
• Không webhook. Xem §7.
• Không có createdAt trong response nội dung (chỉ có updatedAt).

Giữ API key ở phía máy chủ. Key nhúng trong bundle JavaScript hay ứng dụng mobile là key công khai — bất kỳ ai cũng đọc được bằng DevTools hoặc giải nén app. Nếu buộc phải gọi từ trình duyệt, hãy hiểu rõ là bạn đang công khai toàn bộ nội dung học tập kèm đáp án, và chỉ chấp nhận điều đó nếu nội dung vốn được coi là công khai.

Danh sách kiểm tra khi tích hợp

• Key nằm trong biến môi trường / secret store, không commit vào repo.
• Mỗi hệ thống tiêu thụ một key riêng, đặt tên rõ ràng lúc tạo để biết đường thu hồi.
• Có xử lý 401/403: dừng gọi, ghi log, cảnh báo vận hành — không thử lại vòng lặp.
• Có xử lý 404 khi nội dung bị gỡ đăng, không để giao diện hỏng.
• Kiểm tra endQuiz !== null (ở cả cấp chủ đề và cấp khóa học) và options.length > 0 trước khi render.
• Giữ nguyên thứ tự mảng, khoá dữ liệu theo id (không theo slug, không theo chỉ số).
• Nếu chấm điểm cần đáng tin: lược isCorrect ở tầng máy chủ của bạn (§4).
• Nếu render trong trình duyệt: có CSS cho contentHtml (§3) và cho phép iframe nếu sanitize lại.

Xoay key: tạo key mới → cập nhật cấu hình phía tiêu thụ → xác nhận key mới đã hoạt động → thu hồi key cũ. Vì key mới cấp ngay lập tức có hiệu lực, không có thời gian chết.

Liên hệ: mọi việc cấp mới, xoay và thu hồi API key do đội Học viện hàng hóa — Saigon Futures thực hiện. Liên hệ đầu mối kỹ thuật đã trao đổi khi bắt đầu tích hợp.