> ## Documentation Index > Fetch the complete documentation index at: https://developers.fhsc.com.vn/llms.txt > Use this file to discover all available pages before exploring further. # Bảng so sánh các ngành > Danh mục ngành kèm bảng so sánh liên ngành: điểm chỉ số, thay đổi %, vốn hoá, độ rộng, khối lượng / giá trị khớp và mua ròng khối ngoại. `window` quyết định cửa sổ luỹ kế của các field dòng tiền (`volume`, `trading_value`, `foreign_net_value`, `change_percent`). Độ rộng (`advancers`, `decliners`, `unchanged`) chỉ tính được cho phiên hiện tại, nên ngoài `window=1D` các field này trả `null`, và sort/filter theo chúng bị từ chối. Cũng là nơi tra `slug` hợp lệ cho các endpoint `/market/sectors/{slug}/*`. ## OpenAPI ````yaml /openapi.yaml get /market/sectors openapi: 3.1.0 info: title: Finhay Securities Open API version: 0.2.0-preview.3 description: | Đặc tả chính thức của Finhay Securities Open API, dùng chung cho SDK codegen, Redoc docs, và (sau này) mock server / contract test. ## Authentication — 2 tier - **Tier 1 — chỉ cần API key**: các endpoint đọc dữ liệu thị trường (`GET /market/**`, `GET /trading/market/**`). Gửi kèm header `X-FH-APIKEY` là đủ. - **Tier 2 — HMAC signing**: các endpoint liên quan đến account / trading / user. Gửi kèm 4 header `X-FH-APIKEY` + `X-FH-TIMESTAMP` + `X-FH-NONCE` + `X-FH-SIGNATURE`; thêm `X-FH-BODYHASH` khi request có body. Chi tiết thuật toán xem extension `x-finhay-signing` ở root spec hoặc phần README. ## Bootstrap flow Gọi 2 endpoint tag **Khởi tạo** (`GET /users/v1/users/me` và `GET /users/v1/users/{userId}/sub-accounts`) **1 lần khi khởi tạo client** để lấy thông tin `user_id` và `subAccountId`. Mọi endpoint thuộc tag **Tổng tài sản / Tiểu khoản / Danh mục đầu tư / Sổ lệnh / Lãi-lỗ / Quyền cổ đông** đều cần 2 giá trị này để truyền vào path parameter. contact: {} servers: - url: https://open-api.fhsc.com.vn description: Production security: - FinhayApiKey: [] tags: - name: Khởi tạo description: >- Khởi tạo client — lấy `user_id` và `subAccountId`. Gọi 1 lần khi khởi tạo SDK rồi cache lại. - name: Bảng giá thị trường description: >- Giá realtime, lịch sử và sổ lệnh thống nhất cho stocks / indices / forex / crypto / hàng hoá / quỹ mở / trái phiếu / ETF. - name: Phân tích cơ bản description: >- Chỉ số tài chính cơ bản của doanh nghiệp — chỉ số tổng quan, phân tích theo kỳ và báo cáo tài chính chuẩn (income statement / balance sheet / cash flow). - name: Tin tức-sự kiện description: >- Sự kiện doanh nghiệp (cổ tức, quyền mua, ĐHCĐ, …), tin tức stock, tin tức tài chính toàn cầu (forex / commodities / economic-indicators / stock-market / cryptocurrency) và báo cáo khuyến nghị từ analyst. - name: Kinh tế vĩ mô description: >- Chỉ số kinh tế vĩ mô (CPI, PMI, PCE, GDP, …), lãi suất tiền gửi ngân hàng và lịch sự kiện kinh tế. - name: Tổng tài sản description: >- Tổng quan tài sản cấp user — cross-product (stock, fund, bond, hay0) kèm cash, debt, PnL. - name: Tiểu khoản description: Thông tin tiểu khoản — số dư, margin, dư nợ và ngân hàng liên kết. - name: Danh mục đầu tư description: Danh mục stock đang nắm giữ kèm giá realtime và PnL theo vị thế. - name: Sổ lệnh description: >- Quản lý lệnh — sổ lệnh trong ngày, danh sách đầy đủ hoặc chi tiết theo `orderId`. - name: Lãi-lỗ description: PnL và analytics cá nhân — lãi / lỗ trong ngày tổng hợp theo user. - name: Quyền cổ đông description: Quyền cổ đông (cổ tức, quyền mua, bỏ phiếu, …) của tiểu khoản. - name: Phiên giao dịch description: >- Hạ tầng trading — trạng thái phiên giao dịch và order type khả dụng của mỗi exchange. - name: Thực thi lệnh description: | ⚠️ Nhóm endpoint này đang ở giai đoạn **preview**. Đặt / sửa / huỷ lệnh trên sàn — write operation nhạy cảm, yêu cầu Tier 2 HMAC đầy đủ + `X-FH-BODYHASH` + `X-FH-2FA-TOKEN` (daily 2FA session). paths: /market/sectors: get: tags: - Bảng giá thị trường summary: Bảng so sánh các ngành description: > Danh mục ngành kèm bảng so sánh liên ngành: điểm chỉ số, thay đổi %, vốn hoá, độ rộng, khối lượng / giá trị khớp và mua ròng khối ngoại. `window` quyết định cửa sổ luỹ kế của các field dòng tiền (`volume`, `trading_value`, `foreign_net_value`, `change_percent`). Độ rộng (`advancers`, `decliners`, `unchanged`) chỉ tính được cho phiên hiện tại, nên ngoài `window=1D` các field này trả `null`, và sort/filter theo chúng bị từ chối. Cũng là nơi tra `slug` hợp lệ cho các endpoint `/market/sectors/{slug}/*`. operationId: sectorsList parameters: - name: level in: query required: false description: >- Cấp trong cây ICB: `1` = ngành, `3` = nhóm ngành. Bỏ trống → mọi cấp. schema: type: integer enum: - 1 - 3 example: 1 - name: parent in: query required: false description: Chỉ lấy nhóm ngành thuộc ngành cấp 1 này. schema: type: string enum: - technology - telecommunications - healthcare - financials - real-estate - consumer-discretionary - consumer-staples - industrials - basic-materials - energy - utilities example: financials - name: window in: query required: false description: Cửa sổ luỹ kế cho các field dòng tiền. schema: type: string enum: - 1D - 1W - 1M - 3M - 6M - 1Y - YTD default: 1D example: YTD - name: sort in: query required: false description: >- Field sắp xếp, thêm `-` ở đầu để giảm dần. Mặc định `-market_cap`. Field hợp lệ: index_value, change_percent, market_cap, constituent_count, advancers, decliners, unchanged, volume, trading_value, foreign_net_value. schema: type: string example: '-foreign_net_value' - name: fields in: query required: false description: >- Danh sách field cần trả, phân tách bằng dấu phẩy. Mặc định `sector,name,index_value,change_percent`; field dùng trong `sort`/filter luôn được thêm vào. Field hợp lệ: sector, name, level, index_value, change_percent, market_cap, constituent_count, advancers, decliners, unchanged, volume, trading_value, foreign_net_value. schema: type: string example: sector,name,market_cap,foreign_net_value - name: index_value_gt in: query required: false description: Chỉ giữ dòng có `index_value` lớn hơn giá trị này. schema: type: number - name: index_value_lt in: query required: false description: Chỉ giữ dòng có `index_value` nhỏ hơn giá trị này. schema: type: number - name: change_percent_gt in: query required: false description: Chỉ giữ dòng có `change_percent` lớn hơn giá trị này. schema: type: number - name: change_percent_lt in: query required: false description: Chỉ giữ dòng có `change_percent` nhỏ hơn giá trị này. schema: type: number - name: market_cap_gt in: query required: false description: Chỉ giữ dòng có `market_cap` lớn hơn giá trị này. schema: type: number - name: market_cap_lt in: query required: false description: Chỉ giữ dòng có `market_cap` nhỏ hơn giá trị này. schema: type: number - name: constituent_count_gt in: query required: false description: Chỉ giữ dòng có `constituent_count` lớn hơn giá trị này. schema: type: number - name: constituent_count_lt in: query required: false description: Chỉ giữ dòng có `constituent_count` nhỏ hơn giá trị này. schema: type: number - name: advancers_gt in: query required: false description: Chỉ giữ dòng có `advancers` lớn hơn giá trị này. schema: type: number - name: advancers_lt in: query required: false description: Chỉ giữ dòng có `advancers` nhỏ hơn giá trị này. schema: type: number - name: decliners_gt in: query required: false description: Chỉ giữ dòng có `decliners` lớn hơn giá trị này. schema: type: number - name: decliners_lt in: query required: false description: Chỉ giữ dòng có `decliners` nhỏ hơn giá trị này. schema: type: number - name: unchanged_gt in: query required: false description: Chỉ giữ dòng có `unchanged` lớn hơn giá trị này. schema: type: number - name: unchanged_lt in: query required: false description: Chỉ giữ dòng có `unchanged` nhỏ hơn giá trị này. schema: type: number - name: volume_gt in: query required: false description: Chỉ giữ dòng có `volume` lớn hơn giá trị này. schema: type: number - name: volume_lt in: query required: false description: Chỉ giữ dòng có `volume` nhỏ hơn giá trị này. schema: type: number - name: trading_value_gt in: query required: false description: Chỉ giữ dòng có `trading_value` lớn hơn giá trị này. schema: type: number - name: trading_value_lt in: query required: false description: Chỉ giữ dòng có `trading_value` nhỏ hơn giá trị này. schema: type: number - name: foreign_net_value_gt in: query required: false description: Chỉ giữ dòng có `foreign_net_value` lớn hơn giá trị này. schema: type: number - name: foreign_net_value_lt in: query required: false description: Chỉ giữ dòng có `foreign_net_value` nhỏ hơn giá trị này. schema: type: number - name: page in: query required: false description: Trang cần lấy, bắt đầu từ 1. schema: type: integer minimum: 1 example: 1 - name: page_size in: query required: false description: Số ngành mỗi trang, tối đa 50. schema: type: integer minimum: 1 maximum: 50 example: 20 responses: '200': description: >- `data.items` là danh sách ngành, mỗi item chỉ chứa các field được chọn qua `fields`. content: application/json: schema: $ref: '#/components/schemas/SectorCollectionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' x-codeSamples: - lang: bash label: cURL source: | curl -H "X-FH-APIKEY: $FINHAY_API_KEY" \ "https://open-api.fhsc.com.vn/market/sectors?window=YTD&sort=-foreign_net_value" components: schemas: SectorCollectionResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - data properties: data: $ref: '#/components/schemas/SectorCollection' EnvelopeBase: type: object description: | Các field chung của envelope trong mọi response của Finhay API. - `error_code` là `"0"` (string) khi thành công, mã khác `"0"` khi lỗi. - `message` là thông điệp ngắn từ server. properties: error_code: type: string description: '`"0"` khi thành công, khác `"0"` khi lỗi.' example: '0' message: type: string description: Thông điệp trạng thái dễ đọc. example: success SectorCollection: type: object description: Bảng so sánh liên ngành, đã phân trang. required: - items properties: window: type: string description: Cửa sổ luỹ kế đã áp dụng. example: 1D updated_at: type: - string - 'null' format: date-time description: >- Thời điểm dữ liệu được làm mới lần cuối (ISO 8601 kèm offset), không phải lúc gọi API. `null` khi nguồn không ghi thời điểm. example: '2026-08-17T14:30:15+07:00' page: type: integer description: Trang hiện tại. example: 1 page_size: type: integer description: Số ngành mỗi trang. example: 20 total: type: integer description: Tổng số ngành khớp bộ lọc. example: 11 items: type: array description: Danh sách ngành. items: $ref: '#/components/schemas/SectorSummaryItem' ErrorBody: type: object description: Body của response khi 4xx / 5xx. properties: error_code: type: string description: >- Mã lỗi khác `"0"` (ví dụ `AUTH_SIGNATURE_INVALID`, `RATE_LIMIT_EXCEEDED`, …). example: '400' message: type: string description: Thông điệp lỗi (tiếng Anh, từ server). example: Invalid parameter required: - error_code - message SectorSummaryItem: type: object description: >- Một dòng của bảng ngành. Chỉ chứa các field được chọn qua `fields` (mặc định `sector`, `name`, `index_value`, `change_percent`), cộng thêm field dùng trong `sort`/filter. properties: sector: type: string description: Slug ngành. example: financials name: type: string description: Tên ngành. example: Tài chính level: type: integer description: 'Cấp trong cây ICB: 1 = ngành, 3 = nhóm ngành.' example: 1 index_value: type: - number - 'null' description: Điểm chỉ số ngành. example: 1284.32 change_percent: type: - number - 'null' description: Thay đổi so với tham chiếu (%), theo `window`. example: 0.87 market_cap: type: - number - 'null' description: Vốn hoá toàn ngành (VND). example: 1430000000000000 constituent_count: type: - number - 'null' description: Số mã thuộc ngành. example: 87 advancers: type: - number - 'null' description: Số mã tăng giá. `null` khi `window` khác `1D`. example: 42 decliners: type: - number - 'null' description: Số mã giảm giá. `null` khi `window` khác `1D`. example: 31 unchanged: type: - number - 'null' description: Số mã đứng giá. `null` khi `window` khác `1D`. example: 14 volume: type: - number - 'null' description: Khối lượng khớp trong `window`. example: 128450000 trading_value: type: - number - 'null' description: Giá trị khớp trong `window` (VND). example: 3870000000000 foreign_net_value: type: - number - 'null' description: >- Giá trị mua ròng của khối ngoại trong `window` (VND). Âm là bán ròng. example: -184000000000 responses: BadRequest: description: Request không hợp lệ — thiếu hoặc sai tham số. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: error_code: '400' message: Invalid parameter Unauthorized: description: Không xác thực — thiếu, sai hoặc không hợp lệ chữ ký / API key. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: error_code: '401' message: Invalid signature RateLimited: description: >- Vượt giới hạn rate limit. Chờ đến thời điểm `X-RateLimit-Reset` rồi thử lại. headers: X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: error_code: '429' message: Too many requests InternalError: description: Lỗi server nội bộ. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: error_code: '500' message: Internal server error headers: XRateLimitReset: description: | Unix timestamp (giây) — thời điểm window rate limit reset. Client nhận `429 Too Many Requests` nên chờ đến thời điểm này rồi retry. schema: type: integer format: int64 example: 1713441600 securitySchemes: FinhayApiKey: type: apiKey in: header name: X-FH-APIKEY description: > API key dài hạn của client. Cấu hình 1 lần lúc khởi tạo; có thể wire thẳng vào static setter của SDK tự-gen. Đi kèm với `FINHAY_API_SECRET` — secret này chỉ dùng ở phía client để tính `X-FH-SIGNATURE`, **không** bao giờ gửi qua mạng. ````