Changelog

​

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 <field>_gt / <field>_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, …).

​

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 <field>_gt / <field>_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.

​

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ý.

​

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.

​

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).

​

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/**.

​

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).

​

Khởi tạo (2 endpoint)

​

Dữ liệu thị trường (20 endpoint)

• 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)

​

Giao dịch (7 endpoint)

• 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

• 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.