Skip to main content
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.
​
device_id bắt buộc khi đặt/sửa/huỷ lệnh
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ý.
​
Chỉ số thị trường realtime
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.
​
Thực thi lệnh (preview) + cleanup
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/**.
​
Quỹ mở + Global News
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).
​
v0.1.0 — Initial public release
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.