> ## 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. # Lịch sự kiện thị trường > Lịch các sự kiện thị trường theo ngày, **không gắn với mã cổ phiếu**. Hiện trả về sự kiện công bố số liệu vĩ mô (FOMC / quyết định lãi suất, CPI, GDP, PMI, …) của 6 nền kinh tế — Trung Quốc, Khu vực đồng Euro, Nhật Bản, Mỹ, Anh, Việt Nam. Mỗi sự kiện có `type` phân loại (hiện chỉ `ECONOMIC`) và phần đặc thù nằm trong `detail`. Với sự kiện vĩ mô, `detail` gồm số liệu `actual` (thực tế), `previous` (kỳ trước), `consensus` (đồng thuận thị trường) và `forecast` (dự báo) — dạng chuỗi số đã bỏ ký hiệu đơn vị, `null` khi sự kiện chưa diễn ra hoặc nguồn chưa có số — kèm `unit` là đơn vị chung của 4 số liệu (ví dụ `Percent`, `Thousand`, `USD Billion`). Khoảng thời gian lọc qua `from`/`to` (Unix timestamp tính bằng GIÂY). Bỏ trống cả hai thì mặc định lấy sự kiện từ hôm nay trở đi. Sort theo `detail.date` tăng dần, phân trang qua `page`/`page_size`. ## OpenAPI ````yaml /openapi.yaml get /market/calendar 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/calendar: get: tags: - Kinh tế vĩ mô summary: Lịch sự kiện thị trường description: > Lịch các sự kiện thị trường theo ngày, **không gắn với mã cổ phiếu**. Hiện trả về sự kiện công bố số liệu vĩ mô (FOMC / quyết định lãi suất, CPI, GDP, PMI, …) của 6 nền kinh tế — Trung Quốc, Khu vực đồng Euro, Nhật Bản, Mỹ, Anh, Việt Nam. Mỗi sự kiện có `type` phân loại (hiện chỉ `ECONOMIC`) và phần đặc thù nằm trong `detail`. Với sự kiện vĩ mô, `detail` gồm số liệu `actual` (thực tế), `previous` (kỳ trước), `consensus` (đồng thuận thị trường) và `forecast` (dự báo) — dạng chuỗi số đã bỏ ký hiệu đơn vị, `null` khi sự kiện chưa diễn ra hoặc nguồn chưa có số — kèm `unit` là đơn vị chung của 4 số liệu (ví dụ `Percent`, `Thousand`, `USD Billion`). Khoảng thời gian lọc qua `from`/`to` (Unix timestamp tính bằng GIÂY). Bỏ trống cả hai thì mặc định lấy sự kiện từ hôm nay trở đi. Sort theo `detail.date` tăng dần, phân trang qua `page`/`page_size`. operationId: calendarListEvents parameters: - name: country in: query required: false description: Lọc theo quốc gia. Bỏ qua để lấy mọi quốc gia hỗ trợ. schema: $ref: '#/components/schemas/EconomicCountry' - name: from in: query required: false description: Mốc đầu khoảng lọc — Unix timestamp tính bằng GIÂY. schema: type: integer minimum: 0 example: 1767225600 - name: to in: query required: false description: Mốc cuối khoảng lọc — Unix timestamp tính bằng GIÂY, phải >= `from`. schema: type: integer minimum: 0 example: 1769904000 - name: page in: query required: false description: Trang (bắt đầu từ 1). Mặc định 1. schema: type: integer minimum: 1 example: 1 - name: page_size in: query required: false description: Số sự kiện mỗi trang (1–50). Mặc định 20. schema: type: integer minimum: 1 maximum: 50 example: 20 responses: '200': description: '`data` là trang sự kiện kèm `results` và thông tin phân trang.' content: application/json: schema: $ref: '#/components/schemas/CalendarEventsPageResponse' example: error_code: '0' message: success data: results: - type: ECONOMIC country: United States title: Fed Interest Rate Decision detail: date: '2026-07-29T01:00:00+07:00' category: Interest Rate actual: null previous: '5.25' consensus: '5.50' forecast: '5.50' unit: Percent - type: ECONOMIC country: Vietnam title: CPI MoM detail: date: '2026-07-29T00:00:00+07:00' category: Inflation actual: null previous: '0.2' consensus: '0.3' forecast: '0.3' unit: Percent total: 137 current_page: 1 next_page: 2 previous_page: 1 page_size: 20 page_total: 7 '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/calendar?country=United%20States&page=1&page_size=20" components: schemas: EconomicCountry: type: string description: | Tên quốc gia hiển thị (full name) cho dữ liệu kinh tế. Dùng trong `/market/calendar`. | Giá trị | Ý nghĩa | |---------|---------| | `China` | Trung Quốc | | `Euro Area` | Khu vực đồng Euro | | `Japan` | Nhật Bản | | `United States` | Mỹ | | `United Kingdom` | Anh | | `Vietnam` | Việt Nam | enum: - China - Euro Area - Japan - United States - United Kingdom - Vietnam x-enum-varnames: - CHINA - EURO_AREA - JAPAN - UNITED_STATES - UNITED_KINGDOM - VIETNAM CalendarEventsPageResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - data properties: data: $ref: '#/components/schemas/CalendarEventsPage' 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 CalendarEventsPage: allOf: - $ref: '#/components/schemas/PageMeta' - type: object required: - results properties: results: type: array items: $ref: '#/components/schemas/CalendarEvent' description: Sự kiện của trang hiện tại, sort `detail.date` tăng dần. 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 PageMeta: type: object description: > Metadata phân trang dùng chung cho mọi list API. Dữ liệu của trang nằm ở `results`. required: - total - current_page - page_size properties: total: type: integer description: Tổng số bản ghi khớp bộ lọc. example: 137 current_page: type: integer description: Trang hiện tại. example: 1 next_page: type: integer description: Trang kế tiếp; bằng `current_page` khi đã ở trang cuối. example: 2 previous_page: type: integer description: Trang trước; bằng 1 khi đang ở trang đầu. example: 1 page_size: type: integer description: Số bản ghi mỗi trang. example: 20 page_total: type: integer description: Tổng số trang. example: 7 CalendarEvent: type: object description: >- 1 sự kiện trên lịch thị trường. Các trường chung nằm ở cấp ngoài, phần đặc thù theo `type` nằm trong `detail` — thêm loại lịch mới không phá contract cũ. required: - type - country - title - detail properties: type: type: string enum: - ECONOMIC description: Loại sự kiện. Hiện chỉ có `ECONOMIC` (công bố số liệu vĩ mô). example: ECONOMIC country: allOf: - $ref: '#/components/schemas/EconomicCountry' description: Quốc gia của sự kiện. title: type: string description: Tên sự kiện (ví dụ "Fed Interest Rate Decision", "CPI MoM"). example: Fed Interest Rate Decision detail: allOf: - $ref: '#/components/schemas/EconomicEventDetail' description: Chi tiết theo `type`; với `ECONOMIC` là số liệu công bố. EconomicEventDetail: type: object description: Phần đặc thù của sự kiện vĩ mô (`type = ECONOMIC`). required: - date - category properties: date: type: string format: date-time description: Thời điểm diễn ra sự kiện, ISO 8601 kèm offset (giờ Việt Nam). example: '2026-07-29T01:00:00+07:00' category: type: string description: >- Phân loại sự kiện (ví dụ "Interest Rate", "Inflation", "Employment"). example: Interest Rate actual: type: - string - 'null' description: >- Số liệu thực tế đã công bố, dạng chuỗi số đã bỏ ký hiệu đơn vị (đơn vị nằm ở `unit`). `null` khi sự kiện chưa diễn ra. Riêng phiếu bầu BoE MPC giữ nguyên dạng tỉ lệ như "3/9". example: '5.50' previous: type: - string - 'null' description: >- Số liệu kỳ trước, cùng định dạng và đơn vị với `actual`. `null` nếu nguồn không có. example: '5.25' consensus: type: - string - 'null' description: >- Đồng thuận thị trường (consensus), cùng định dạng và đơn vị với `actual`. `null` nếu nguồn không có. example: '5.50' forecast: type: - string - 'null' description: >- Dự báo nhà phân tích, cùng định dạng và đơn vị với `actual`. `null` nếu nguồn không có. example: '5.50' unit: type: - string - 'null' description: >- Đơn vị chung của `actual`/`previous`/`consensus`/`forecast`: `Percent`, `Thousand`, `Million`, `Billion`, `Trillion`, `Billion Cubic Feet`, hoặc tiền tệ kèm bậc như `USD Billion`, `GBP Billion`, `JPY Billion`, `EUR Billion`, `CNY Billion`, `USD Trillion`. `null` khi giá trị là chỉ số thuần (PMI, CPI index, số giàn khoan…) hoặc chưa có số liệu. example: Percent 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. ````