Quickstart Guide

This guide helps you get started and send your first requests to the HocChungKhoan CMS API using cURL or any HTTP client (such as Postman, Bruno).

---

🌎 Environment & Base URL

All API endpoints are deployed at:

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

---

🔑 Authentication & Authorization

• Public APIs: Endpoints querying customer profiles, portfolios, transactions, and stats are Public (no API key required) when queried via the customer slug.
• Admin APIs: The synchronization endpoint /api/sync requires the X-Admin-Key authentication header.

---

⚡ Basic Requests

Here are query examples using the sample customer slug bangnh (Nguyen Huu Bang):

1. Get Customer Details

Retrieve contact info and associated broker accounts:

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

Example Response (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. Get Portfolio Holdings

Retrieve current stock holdings, quantities, and average buy costs:

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

3. Get Aggregated Data (All-in-one)

To optimize load times and performance on frontend dashboards, use the aggregate endpoint to fetch profile, portfolio, stats, and analytics in a single call:

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

---

🚨 Error Handling

The API returns standard HTTP status codes and JSON error objects:

HTTP Status	Meaning	Common Cause
401 Unauthorized	Invalid credentials	Missing or incorrect X-Admin-Key header
404 Not Found	Resource not found	The provided customer slug does not exist
500 Internal Error	Server error	Database connection failure or internal logic issues

Example 404 Error:

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