Chuyển tới nội dung chính

Bắt đầu nhanh với API

Hướng dẫn này giúp bạn làm quen và gửi các request đầu tiên đến HocChungKhoan CMS API bằng cURL hoặc bất kỳ HTTP client nào (như Postman, Bruno).

🌎 Môi trường & Base URL​

Tất cả các API được triển khai tại địa chỉ:

  • Production URL: https://api.hocchungkhoan.com.vn

🔑 Xác thực & Quyền truy cập​

  • Public APIs: Các API lấy thông tin khách hàng, danh mục, giao dịch và thống kê là Public (không yêu cầu API key) khi truy cập dữ liệu qua slug.
  • Admin APIs: API đồng bộ dữ liệu /api/sync yêu cầu Header xác thực X-Admin-Key.

⚡ Các Request Cơ bản​

Dưới đây là các ví dụ truy vấn dữ liệu của khách hàng mẫu có slug bangnh (Nguyen Huu Bang):

1. Lấy thông tin khách hàng​

Truy vấn thông tin cá nhân và danh sách các tài khoản chứng khoán liên kết:

curl -X GET "https://api.hocchungkhoan.com.vn/api/customers/bangnh"

Response mẫu (200 OK):

{
  "success": true,
  "data": {
    "id": "e5b3060c-26d4-4bb8-8d4e-d0076a084c7a",
    "slug": "bangnh",
    "name": "Nguyen Huu Bang",
    "email": "bangnh@example.com",
    "phone": "0987654321",
    "accounts": [
      {
        "id": "c1b07384-b113-4ec2-a5d6-c95a2d67d7e3",
        "account_no": "0001234567",
        "broker": {
          "name": "SSI Securities",
          "code": "SSI"
        }
      }
    ]
  }
}

2. Lấy danh mục đầu tư (Portfolio holdings)​

Lấy các mã chứng khoán hiện đang nắm giữ, khối lượng và giá vốn trung bình:

curl -X GET "https://api.hocchungkhoan.com.vn/api/portfolio/bangnh"

3. Lấy dữ liệu tổng hợp (All-in-one)​

Để tối ưu hóa hiệu năng tải trang cho dashboard frontend, hãy sử dụng endpoint aggregate để nhận toàn bộ thông tin (hồ sơ, danh mục, stats, analytics) chỉ trong 1 request:

curl -X GET "https://api.hocchungkhoan.com.vn/api/aggregate/bangnh"

🚨 Xử lý Lỗi​

Hệ thống trả về mã trạng thái HTTP tiêu chuẩn và đối tượng lỗi dạng JSON:

HTTP StatusÝ nghĩaLý do phổ biến
401 UnauthorizedSai thông tin xác thựcQuên truyền header X-Admin-Key hoặc key không đúng
404 Not FoundKhông tìm thấy tài nguyênKhách hàng có slug đó không tồn tại trong hệ thống
500 Internal ErrorLỗi máy chủLỗi kết nối database hoặc logic xử lý nội bộ

Ví dụ lỗi 404:

{
  "success": false,
  "error": "Customer not found"
}