> ## Documentation Index > Fetch the complete documentation index at: https://hoalulab.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Nhật ký thay đổi > Lịch sử thay đổi của Finhay Securities Open API. Trang này ghi lại các thay đổi của API và tài liệu qua từng phiên bản. **BREAKING** — `GET /market/recommendation-reports/{symbol}` bị **gỡ bỏ**, thay bằng `GET /market/stocks/{symbol}/analyst-reports`. Tham số `date` bị bỏ khỏi 4 endpoint snapshot `/market/stocks/{symbol}/trading`, `/trading/foreign`, `/trading/proprietary`, `/trading/orders` — luôn trả phiên gần nhất có dữ liệu; lấy phiên cũ hơn qua bản `/history`. Tổng số endpoint: 68 → 83. ### Phân tích theo chỉ số — `/market/indices/**` (5 endpoint) * `GET /market/indices` — bảng so sánh các chỉ số: điểm, thay đổi %, vốn hoá, độ rộng, dòng tiền; hỗ trợ `window`, `sort`, `fields`, filter `_gt` / `_lt`, phân trang. * `/{symbol}/breadth`, `/{symbol}/constituents`, `/{symbol}/trading/foreign` và `/{symbol}/trading/foreign/history` cho VNINDEX, HNXINDEX, UPCOMINDEX, VN30, HNX30. ### Phân tích theo ngành — `/market/sectors/**` (7 endpoint) * `GET /market/sectors` — bảng so sánh ngành theo cây ICB (`level`, `parent`), cũng là nơi tra `slug` hợp lệ. * `/{slug}/breadth`, `/{slug}/constituents`, `/{slug}/performance` (+ `/history`), `/{slug}/trading/foreign` (+ `/history`). ### Theo mã cổ phiếu * `GET /market/stocks/{symbol}/events` — sự kiện quyền (cổ tức tiền / cổ phiếu, phát hành thêm, ĐHCĐ, chuyển đổi trái phiếu, …); `details` là `oneOf` theo `event_type`. * `GET /market/stocks/{symbol}/trading/insider` — giao dịch nội bộ / cổ đông lớn, lọc theo `side` và `status`. * `GET /market/stocks/{symbol}/analyst-reports` — báo cáo phân tích của CTCK, lọc theo `source`, `recommendation`, khoảng ngày phát hành. * `GET /market/quotes/stocks/{symbol}/order-book/history` — lịch sử sổ lệnh trong phiên. ### Thay đổi khác * `GET /market/company-financial/analysis` và `GET /market/v2/financial-statement/statement` thêm `page` (lùi về quá khứ) và `year` (lọc một năm). * `GET /market/calendar`: `actual` / `previous` / `consensus` / `forecast` giờ là chuỗi số đã bỏ ký hiệu đơn vị (`"5.50"` thay vì `"5.50%"`), đơn vị tách ra field mới `unit` (`Percent`, `Thousand`, `USD Billion`, …). **BREAKING** — Toàn bộ nhóm dữ liệu thị trường được thiết kế lại: 32 endpoint cũ (`/market/stock-realtime`, `/market/index-realtime`, `/market/price-histories-chart`, `/market/news`, `/market/financial-data/**`, `/fund-trading/public/**`) bị **gỡ bỏ** và thay bằng 50 endpoint mới. Tổng số endpoint: 50 → 68. ### Bảng giá thống nhất — `/market/quotes/**` (30 endpoint) * Một mô hình chung cho 8 loại tài sản: `stocks`, `indices`, `forex`, `cryptos`, `commodities`, `funds`, `bonds`, `etfs`. Mỗi loại có catalog (`/market/quotes/{loại}`), quote realtime (`/{symbol}`) và lịch sử (`/{symbol}/history`); `stocks` / `bonds` / `etfs` thêm `/order-book`. * Hàng hoá có thêm 3 endpoint giá theo nhà cung cấp (`/commodities/{symbol}/dealer-products/**`) — thay cho `gold-providers` / `metal-providers` cũ. * `symbol` không phân biệt hoa thường; `from` / `to` của history là Unix timestamp tính bằng **giây**. ### Screener và thống kê giao dịch — `/market/stocks/**` (15 endpoint) * `GET /market/stocks` — screener toàn thị trường: filter phạm vi (`exchange` / `index` / `sector`), filter số dạng `_gt` / `_lt`, `sort`, `window` hoặc `date`, `fields`, phân trang. * Thống kê theo mã: khối ngoại, tự doanh, thống kê lệnh mua / bán, room ngoại và chỉ báo kỹ thuật — mỗi loại có bản snapshot và bản `/history`. * Hồ sơ doanh nghiệp: `/profile`, `/listing`, `/ownership` (tag `Phân tích cơ bản`). ### Tin tức và vĩ mô * `GET /market/market-news` + `/market/market-news/{id}` — tin tức thị trường phân trang, lọc theo `topic` (kết hợp `symbol` khi `topic=stock`). Thay cho `/market/news` và `financial-data/global-news`. * `GET /market/macro/indicators` + `/{indicator}` — catalog chỉ tiêu vĩ mô và chuỗi giá trị theo kỳ (`yyyy`, `yyyy-Qn`, `yyyy-MM`). Thay cho `financial-data/macro` và `financial-data/trading-economics`. * `GET /market/calendar` — lịch sự kiện kinh tế của 6 nền kinh tế, thay cho `financial-data/economic-calendar-events`. * `GET /market/financial-data/bank-interest-rates` giữ nguyên path nhưng đổi shape: `data.bank_interest_rates` là **mảng** ngân hàng, mỗi ngân hàng có mảng `rates` theo kỳ hạn. ### Taxonomy * 4 tag cũ (`Dữ liệu giao dịch`, `Hàng hoá`, `Tổng hợp đa loại`, `Quỹ mở`) gộp thành 1 tag **`Bảng giá thị trường`**. Nhóm quỹ mở giờ nằm trong `/market/quotes/funds/**`. * Nhóm `/market/**` trả payload trong `data`; nhóm tài khoản / giao dịch giữ nguyên `result`. * Endpoint tài khoản, danh mục, sổ lệnh, PnL, quyền cổ đông, phiên giao dịch và thực thi lệnh **không đổi**. **BREAKING** — Thêm header bắt buộc **`device-id`** vào 3 endpoint nhóm `Thực thi lệnh`. Client cũ chưa gửi header này sẽ nhận `400`. Bump version `0.2.0-preview.2` → `0.2.0-preview.3`. ### Thay đổi * Thêm header parameter bắt buộc `device-id` cho `ordersPlace` / `ordersModify` / `ordersCancel` — **định danh thiết bị đặt lệnh** do client cung cấp mỗi request (phục vụ tuân thủ quy định giao dịch), **không** lấy từ token / phiên xác thực. * Parameter dùng chung mới `DeviceId` (`components/parameters/DeviceId.yaml`). * Không đổi cơ chế ký (`x-finhay-signing` giữ nguyên) — `device_id` chỉ để lưu vết, không nằm trong chữ ký. Bổ sung **1 endpoint** dữ liệu thị trường (tổng 50) dưới tag `Dữ liệu giao dịch`. ### Endpoint mới * `GET /market/index-realtime` — giá trị realtime của chỉ số thị trường chứng khoán Việt Nam (`VNINDEX`, `HNXINDEX`, `UPCOMINDEX`, `VN30`, `HNX30`). Tier 1 — chỉ cần `X-FH-APIKEY`. Truyền nhiều mã phân tách dấu phẩy (`?index=VNINDEX,HNX30`); `result` luôn là array, 1 phần tử cho mỗi mã có dữ liệu. ### Schema * Schema mới `IndexRealtime` — snapshot 1 chỉ số: điểm hiện tại (`indexValue`), thay đổi (`change` / `changePercent`), tham chiếu (`reference`), khối lượng / giá trị khớp (`allQuantity` / `allValue`), breadth (số mã tăng / giảm / đứng giá / trần / sàn) và chuỗi intraday (`values` / `volumes` / `times`). Nhóm `*Arr` / `ceilings` / `floors` chỉ áp dụng cho index KRX. * Enum mới `MarketIndex` — 5 mã chỉ số thị trường Việt Nam. Bổ sung **3 endpoint write** đầu tiên dưới tag `Thực thi lệnh` — đang ở giai đoạn **preview**. Bump version `0.1.0` → `0.2.0-preview.1`. ### Endpoint mới (preview) * `POST /trading/oa/sub-accounts/{subAccountId}/orders` — Đặt lệnh. * `PUT /trading/oa/sub-accounts/{subAccountId}/orders/{orderId}` — Sửa lệnh. * `DELETE /trading/oa/sub-accounts/{subAccountId}/orders/{orderId}` — Huỷ lệnh (DELETE có body — contract upstream). 3 endpoint trên đang ở giai đoạn preview. ### Security mở rộng * Security scheme mới `FinhayTwoFactor` (`X-FH-2FA-TOKEN`) — daily JWT session cấp sau khi user xác thực qua OTP. * Response component mới `Forbidden` (HTTP 403) — bao gồm các mã `OTP_SESSION_REQUIRED|EXPIRED|INVALID|REVOKED`. * `x-finhay-signing.appliesTo.twoFactor` liệt kê 3 route preview cần 2FA token. ### Cleanup tài liệu * Fix drift tên tag trong `info.description` của root spec và 2 README: `Bootstrap` → `Khởi tạo`; `Account / Portfolio / Orders / PnL / Corporate Actions` → tag tiếng Việt thực tế. * Đồng bộ danh sách `API_KEY_ONLY` patterns trong Mintlify `authentication.mdx` (TypeScript + Python middleware) và `introduction.mdx` với `x-finhay-signing.appliesTo.apiKeyOnly` — thêm `/trading/securities/**` và `/fund-trading/public/**`. Bổ sung 16 endpoint mới (tổng 46), giới thiệu nhóm chức năng mới **Quỹ mở** dưới tab dữ liệu thị trường. ### Endpoint mới * **Quỹ mở** (14, tag `Quỹ mở`): danh sách quỹ + công ty quản lý, NAV history + benchmark, holdings (portfolio / asset-allocation / sector-allocation / suggestions), ranking (top AUM / investor / fund-flow / holding-symbols), benchmark cross-fund (growth / nav / operation). Prefix path `/fund-trading/public/**` — Tier 1, chỉ cần `X-FH-APIKEY`. * **Tin tức tài chính toàn cầu** (2, tag `Tin tức-sự kiện`): `/market/financial-data/global-news` (paginated list lọc theo category) + `/market/financial-data/global-news/{id}` (chi tiết bài báo). Tier 1. ### Description / schema tweaks * `ProductsSummary.bond` (`/users/v3/users/{userId}/assets/summary`): field này là sản phẩm HayBond, không phải trái phiếu doanh nghiệp / chính phủ thông thường — clarify trong description. * `assetGetSummary` description: bổ sung guidance combine với `/trading/accounts/{subAccountId}/summary` để có NAV chính xác nhất. ### Path version revert * `/users/v4/users/{userId}/assets/summary` → `/users/v3/users/{userId}/assets/summary` (sync về version hiện hành phía server). Phiên bản đầu tiên công khai của Finhay Securities Open API. API hiện cung cấp **30 endpoint** chia 14 nhóm chức năng, bao trùm 4 mảng chính: ### Khởi tạo (2 endpoint) Bootstrap flow để lấy `userId` và `subAccountId` — bắt buộc trước khi gọi các endpoint user-scoped. ### Dữ liệu thị trường (20 endpoint) Dữ liệu công khai về thị trường tài chính, chỉ cần API key Tier 1: * **Dữ liệu giao dịch** (2): giá stock realtime, lịch sử OHLCV. * **Phân tích cơ bản** (3): chỉ số tài chính tổng quan, phân tích theo kỳ, báo cáo tài chính (income statement / balance sheet / cash flow). * **Tin tức & sự kiện** (2): tin tức stock, báo cáo khuyến nghị từ analyst. * **Kinh tế vĩ mô** (4): chỉ số CPI / PMI / GDP, lãi suất ngân hàng, chỉ số kinh tế lịch sử (Trading Economics), lịch sự kiện kinh tế. * **Hàng hoá** (7): vàng, bạc (spot / chart / theo nhà cung cấp), top crypto trending. * **Tổng hợp đa loại** (2): endpoint composite cross-domain, lịch sử giá instrument toàn cầu (US / Asian indices, Mag7, hàng hoá, forex). ### Người dùng (1 endpoint) Tổng tài sản — cross-product wealth summary của user (stock, fund, bond, cash, debt, PnL). ### Giao dịch (7 endpoint) Thông tin tài khoản và lịch sử giao dịch của user, yêu cầu HMAC signing Tier 2: * **Tiểu khoản** (1): số dư, margin, dư nợ, ngân hàng liên kết. * **Danh mục đầu tư** (1): stock đang nắm giữ kèm PnL theo vị thế. * **Sổ lệnh** (2): lệnh trong ngày — full list hoặc detail theo `orderId`. * **Lãi/lỗ** (1): PnL trong ngày tổng hợp qua mọi tiểu khoản. * **Quyền cổ đông** (1): cổ tức, quyền mua, bỏ phiếu. * **Phiên giao dịch** (1): trạng thái phiên + order type khả dụng. ### Xác thực API chia **2 tier**: * **Tier 1** — chỉ cần header `X-FH-APIKEY`, dùng cho dữ liệu thị trường công khai. * **Tier 2** — HMAC-SHA256 signing đầy đủ, dùng cho endpoint user-scoped. Xem chi tiết ở [Authentication](/vi/fhsc/authentication). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.