# FHSC - Open API docs

> API chính thức của Finhay Securities — dữ liệu thị trường, tài khoản và giao dịch.

## Docs

- [Danh mục stock đang nắm giữ của tiểu khoản](https://developers.fhsc.com.vn/api-reference/danh-mục-đầu-tư/danh-mục-stock-đang-nắm-giữ-của-tiểu-khoản.md): Danh mục stock đang nắm giữ của 1 tiểu khoản, kèm `cost_price` (giá vốn), `basic_price` (giá tham chiếu), `close_price` (giá đóng cửa gần nhất), cùng PnL theo vị thế (`pnl_amount`, `pnl_rate`, `total_pnl`).
- [Giá stock realtime](https://developers.fhsc.com.vn/api-reference/dữ-liệu-giao-dịch/giá-stock-realtime.md): Giá realtime của stock kèm các chỉ số cơ bản — giá hiện tại, % thay đổi, trần / sàn / tham chiếu, OHLC trong phiên, khối lượng / giá trị giao dịch, cap, P/E, P/B, ROE.
- [Lịch sử giá dạng biểu đồ](https://developers.fhsc.com.vn/api-reference/dữ-liệu-giao-dịch/lịch-sử-giá-dạng-biểu-đồ.md): Lịch sử giá OHLCV dạng array columnar — `time[i]`, `open[i]`, `close[i]`, `high[i]`, `low[i]`, `volume[i]` cùng index `i` biểu diễn 1 cây nến.
- [Biểu đồ giá bạc](https://developers.fhsc.com.vn/api-reference/hàng-hoá/biểu-đồ-giá-bạc.md): Biểu đồ giá bạc `days` ngày gần nhất (mặc định 30). Mỗi row có 2 cột snapshot — bạc miếng trong nước và giá bạc thế giới (đã quy đổi), đơn vị nghìn VND / chỉ. (Bạc không có split bar / ring như vàng.)
- [Biểu đồ giá vàng](https://developers.fhsc.com.vn/api-reference/hàng-hoá/biểu-đồ-giá-vàng.md): Biểu đồ giá vàng `days` ngày gần nhất (mặc định 30). Mỗi row có 3 cột snapshot — vàng miếng SJC, vàng nhẫn 9999, và giá vàng thế giới (đã quy đổi), đơn vị nghìn VND / chỉ.
- [Giá bạc](https://developers.fhsc.com.vn/api-reference/hàng-hoá/giá-bạc.md): Giá bạc trong nước (PNJ và các nhà cung cấp) cùng giá bạc thế giới (đã quy đổi). Row shape giống endpoint `/gold` — `vnd_value` đơn vị **VND/lượng**, `usd_value` đơn vị **USD/oz**.
- [Giá vàng](https://developers.fhsc.com.vn/api-reference/hàng-hoá/giá-vàng.md): Giá vàng SJC trong nước cùng giá vàng thế giới (đã quy đổi sang VND). Đơn vị: `vnd_value` đơn vị **VND/lượng**, `usd_value` đơn vị **USD/oz**.
- [Giá vàng theo nhà cung cấp](https://developers.fhsc.com.vn/api-reference/hàng-hoá/giá-vàng-theo-nhà-cung-cấp.md): Giá vàng chia theo nhà cung cấp (PNJ, DOJI, BTMC, SJC, MiHong, …). Row shape giống `/gold` cộng thêm `provider_icon` URL. Đơn vị: `vnd_value` **VND/lượng**, `usd_value` **USD/oz**.
- [Giá vàng và bạc theo nhà cung cấp](https://developers.fhsc.com.vn/api-reference/hàng-hoá/giá-vàng-và-bạc-theo-nhà-cung-cấp.md): Superset của `/gold-providers` — trả về cả giá vàng lẫn bạc của mọi nhà cung cấp trong 1 call duy nhất. Phân biệt vàng / bạc qua field `index` (`*_GOLD` vs `*_SILVER`).
- [Top crypto đang trending](https://developers.fhsc.com.vn/api-reference/hàng-hoá/top-crypto-đang-trending.md): Top crypto đang trending toàn cầu, kèm giá hiện tại, market cap và % thay đổi giá ở các khung thời gian (`1h`, `24h`, `7d`, `30d`) cùng ảnh sparkline 30 ngày (`last_30d_chart`).
- [Danh sách tiểu khoản của user](https://developers.fhsc.com.vn/api-reference/khởi-tạo/danh-sách-tiểu-khoản-của-user.md): Trả về danh sách tiểu khoản của user. Mỗi entry có `id` (dùng làm path variable `{subAccountId}`), `type` (`Normal` hoặc `Margin`), `sub_account_ext`, cùng các field hồ sơ user (`cust_id`, `name`, `depository_number`, `product_type_name`).
- [Lấy thông tin user hiện tại](https://developers.fhsc.com.vn/api-reference/khởi-tạo/lấy-thông-tin-user-hiện-tại.md): Trả về thông tin user hiện tại — đặc biệt là `data.user_id`, giá trị bắt buộc cần truyền vào path variable `{userId}` ở mọi endpoint user-scoped (assets summary, pnl-today, …).
- [Chỉ số kinh tế lịch sử (Trading Economics)](https://developers.fhsc.com.vn/api-reference/kinh-tế-vĩ-mô/chỉ-số-kinh-tế-lịch-sử-trading-economics.md): Dữ liệu chỉ số kinh tế lịch sử lấy từ Trading Economics, lọc theo quốc gia (bắt buộc), nhóm chỉ số (optional), và năm (optional).
- [Dữ liệu vĩ mô](https://developers.fhsc.com.vn/api-reference/kinh-tế-vĩ-mô/dữ-liệu-vĩ-mô.md): Chỉ số kinh tế vĩ mô của Việt Nam hoặc Mỹ. `type` và `country` là bắt buộc.
- [Lãi suất tiền gửi ngân hàng](https://developers.fhsc.com.vn/api-reference/kinh-tế-vĩ-mô/lãi-suất-tiền-gửi-ngân-hàng.md): Lãi suất tiền gửi tiết kiệm của các ngân hàng tại Việt Nam, phân theo kỳ hạn (key dạng `1M`, `3M`, `6M`, `12M`, …). Đơn vị: **% / năm**.
- [Lịch sự kiện kinh tế sắp tới](https://developers.fhsc.com.vn/api-reference/kinh-tế-vĩ-mô/lịch-sự-kiện-kinh-tế-sắp-tới.md): Lịch các sự kiện kinh tế sắp diễn ra trên toàn cầu (CPI release, Fed meeting, PMI announcement, GDP data, …) trong N tuần tới. Cover 6 nền kinh tế lớn — Trung Quốc, Khu vực đồng Euro, Nhật Bản, Mỹ, Anh, Việt Nam.
- [Lãi-lỗ hôm nay](https://developers.fhsc.com.vn/api-reference/lãi-lỗ/lãi-lỗ-hôm-nay.md): Lãi / lỗ trong ngày của user, tổng hợp qua mọi tiểu khoản.
- [Trạng thái phiên giao dịch](https://developers.fhsc.com.vn/api-reference/phiên-giao-dịch/trạng-thái-phiên-giao-dịch.md): Trạng thái phiên giao dịch hiện tại của 1 sàn cùng danh sách order type đang được nhận. Ví dụ `ATO` chỉ khả dụng trong phiên `OPEN` của HOSE, `ATC` chỉ khả dụng phiên `CLOSE`. Dùng để gating UI place-order.
- [Báo cáo tài chính](https://developers.fhsc.com.vn/api-reference/phân-tích-cơ-bản/báo-cáo-tài-chính.md): Báo cáo kết quả kinh doanh / bảng cân đối kế toán / lưu chuyển tiền tệ của 1 mã stock, theo format wide — **mỗi row là 1 kỳ báo cáo**, các metric code nằm theo cột. `year` luôn có; `quarter` chỉ có khi `period=quarterly` (giá trị `1`–`4`).
- [Chỉ số tài chính tổng quan của doanh nghiệp](https://developers.fhsc.com.vn/api-reference/phân-tích-cơ-bản/chỉ-số-tài-chính-tổng-quan-của-doanh-nghiệp.md): Các chỉ số tài chính quan trọng của 1 mã stock. `industry` chứa giá trị trung bình của ngành cho cùng bộ chỉ số. `nim` chỉ có ý nghĩa với ngân hàng; `margin_loan_to_equity_ratio` chỉ có với công ty chứng khoán.
- [Phân tích tài chính doanh nghiệp theo kỳ](https://developers.fhsc.com.vn/api-reference/phân-tích-cơ-bản/phân-tích-tài-chính-doanh-nghiệp-theo-kỳ.md): Các chỉ số tài chính theo kỳ. Mỗi row luôn có `year`; `quarter` chỉ có khi `period=quarterly`.
- [Quyền cổ đông của tiểu khoản](https://developers.fhsc.com.vn/api-reference/quyền-cổ-đông/quyền-cổ-đông-của-tiểu-khoản.md): Quyền cổ đông (cổ tức, quyền mua stock, bỏ phiếu, …) của tiểu khoản. Kết quả được sort theo `reportDate` giảm dần.
- [Chi tiết 1 lệnh trong sổ lệnh](https://developers.fhsc.com.vn/api-reference/sổ-lệnh/chi-tiết-1-lệnh-trong-sổ-lệnh.md): Chi tiết đầy đủ 1 lệnh — toàn bộ field giống item trong order-book list, nhưng trả về single object thay vì array. Status code map (`status_code`): `01` = SENT (đã gửi sàn), `02` = PARTIAL (khớp 1 phần), `03` = FILLED (khớp đủ), `04` = CANCELLED, `05` = REJECTED.
- [Lấy sổ lệnh trong ngày](https://developers.fhsc.com.vn/api-reference/sổ-lệnh/lấy-sổ-lệnh-trong-ngày.md): Sổ lệnh (orderbook) đầy đủ trong ngày (bao gồm cả lệnh từ broker-signal và HayBond).
- [Báo cáo khuyến nghị theo stock](https://developers.fhsc.com.vn/api-reference/tin-tức-sự-kiện/báo-cáo-khuyến-nghị-theo-stock.md): Báo cáo khuyến nghị (research report) của các công ty chứng khoán cho 1 mã stock. Khi stock có báo cáo, `data` là object chứa `recommendation` (khuyến nghị mới nhất, plain text) và `recommendationReports[]` (danh sách báo cáo gốc kèm download URL). Khi stock không có báo cáo nào, `data` là `[]`.
- [Sự kiện doanh nghiệp-tin tức stock](https://developers.fhsc.com.vn/api-reference/tin-tức-sự-kiện/sự-kiện-doanh-nghiệp-tin-tức-stock.md): Sự kiện doanh nghiệp (cổ tức, quyền mua, ngày ĐHCĐ, …) lọc theo mã stock và / hoặc khoảng thời gian. `from_date` / `to_date` dùng format `DD/MM/YYYY`. Nếu bỏ qua, mặc định lấy 12 tháng gần nhất. Trả về `[]` khi không có kết quả.
- [Chi tiết số dư, margin, dư nợ của tiểu khoản](https://developers.fhsc.com.vn/api-reference/tiểu-khoản/chi-tiết-số-dư-margin-dư-nợ-của-tiểu-khoản.md): Thông tin chi tiết của tiểu khoản — số dư, dư nợ, margin, tài sản ròng và thông tin ngân hàng liên kết.
- [Lịch sử giá instrument toàn cầu (index / Mag7 / hàng hoá / forex)](https://developers.fhsc.com.vn/api-reference/tổng-hợp-đa-loại/lịch-sử-giá-instrument-toàn-cầu-index-mag7-hàng-hoá-forex.md): Lịch sử giá đóng cửa của 1 instrument toàn cầu, phân loại qua param `type`. Cover 4 nhóm asset:
- [Tổng hợp mọi loại dữ liệu tài chính](https://developers.fhsc.com.vn/api-reference/tổng-hợp-đa-loại/tổng-hợp-mọi-loại-dữ-liệu-tài-chính.md): Endpoint tổng hợp giá vàng, bạc, crypto, lãi suất ngân hàng, tỷ giá USD và US index trong 1 call duy nhất. Nên dùng các endpoint chuyên biệt nếu chỉ cần 1 loại dữ liệu.
- [Tổng quan tài sản của user](https://developers.fhsc.com.vn/api-reference/tổng-tài-sản/tổng-quan-tài-sản-của-user.md): Tổng quan số dư và tài sản của user: tài sản ròng, chi tiết từng loại sản phẩm (stock / fund / bond / hay0), tiền mặt, dư nợ và PnL.
- [Authentication](https://developers.fhsc.com.vn/authentication.md): 2 tier xác thực: API key đơn giản và HMAC signing đầy đủ.
- [Bootstrap flow](https://developers.fhsc.com.vn/bootstrap-flow.md): Cách lấy userId và subAccountId trước khi gọi các endpoint trading.
- [Changelog](https://developers.fhsc.com.vn/changelog.md): Lịch sử thay đổi của Finhay Securities Open API.
- [Error codes](https://developers.fhsc.com.vn/errors.md): Bảng tra cứu mã lỗi, HTTP status mapping và chiến lược xử lý.
- [Overview](https://developers.fhsc.com.vn/introduction.md): API chính thức để tích hợp dữ liệu thị trường, thông tin tài khoản và lịch sử giao dịch của Finhay Securities.
- [Quickstart](https://developers.fhsc.com.vn/quickstart.md): Gọi request đầu tiên trong 5 phút — không cần HMAC signing.
- [Rate limits](https://developers.fhsc.com.vn/rate-limits.md): Giới hạn request per API key và chiến lược retry khi bị throttled.

## OpenAPI Specs

- [openapi](https://developers.fhsc.com.vn/openapi.yaml)