> ## 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. # Sự kiện quyền của stock > Sự kiện quyền của 1 mã (nguồn CAMAST của VSD), gồm cả sự kiện tương lai đã công bố. Sắp xếp theo ngày GDKHQ giảm dần, sự kiện chưa có ngày chốt xếp cuối. ## OpenAPI ````yaml /openapi.yaml get /market/stocks/{symbol}/events 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/stocks/{symbol}/events: get: tags: - Tin tức-sự kiện summary: Sự kiện quyền của stock description: >- Sự kiện quyền của 1 mã (nguồn CAMAST của VSD), gồm cả sự kiện tương lai đã công bố. Sắp xếp theo ngày GDKHQ giảm dần, sự kiện chưa có ngày chốt xếp cuối. operationId: stocksGetEvents parameters: - name: symbol in: path required: true description: >- Mã cổ phiếu niêm yết (3–10 ký tự chữ/số, không phân biệt hoa thường). VD: VNM, FPT. schema: type: string example: VNM - name: from in: query required: false description: >- Ngày bắt đầu (bao gồm), lọc theo `dates.ex_date`, dạng `YYYY-MM-DD`. Bỏ trống → không giới hạn. schema: type: string format: date example: '2026-01-01' - name: to in: query required: false description: >- Ngày kết thúc (bao gồm), lọc theo `dates.ex_date`, dạng `YYYY-MM-DD`. Bỏ trống → không giới hạn. schema: type: string format: date example: '2026-12-31' - name: event_type in: query required: false description: >- Lọc theo loại quyền (`RightEventType`, vd `CASH_DIVIDEND`), danh mục đầy đủ 26 giá trị. Bỏ trống → mọi loại. schema: $ref: '#/components/schemas/RightEventType' example: CASH_DIVIDEND - name: page in: query required: false description: Trang cần lấy, 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ố bản ghi mỗi trang, tối đa 50. Mặc định `20`. schema: type: integer minimum: 1 maximum: 50 example: 20 responses: '200': description: '`data.events` là danh sách sự kiện quyền của trang hiện tại.' content: application/json: schema: $ref: '#/components/schemas/RightEventListResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '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/stocks/VNM/events?event_type=CASH_DIVIDEND" components: schemas: RightEventType: type: string description: >- Mã loại quyền, danh mục đầy đủ 26 giá trị. Chỉ 11 giá trị sau có schema `details` riêng (xem `RightEventDetails`) vì liên quan trực tiếp quyền lợi cổ đông/trái chủ — các giá trị còn lại là sự kiện quản trị/thị trường, `details` sẽ là `null`: `SHAREHOLDER_MEETING` = Tham dự đại hội cổ đông; `CASH_DIVIDEND` = Chia cổ tức bằng tiền; `STOCK_DIVIDEND` = Chia cổ tức bằng cổ phiếu; `RIGHTS_OFFERING` = Quyền mua; `BOND_INTEREST` = Trả lãi trái phiếu; `BOND_PRINCIPAL_INTEREST` = Trả gốc và lãi trái phiếu; `BOND_TO_STOCK_CONVERSION` = Chuyển đổi trái phiếu thành cổ phiếu; `STOCK_TO_STOCK_CONVERSION` = Chuyển đổi cổ phiếu thành cổ phiếu; `BONUS_SHARE` = Cổ phiếu thưởng; `CONVERTIBLE_BOND_OPTION` = Chuyển đổi trái phiếu (chọn nhận CP hoặc tiền); `COVERED_WARRANT_SETTLEMENT` = Chi trả lợi tức chứng quyền. Các giá trị không có details: `AUCTION` = Đấu giá; `TRADING_SUSPENSION` = Tạm ngừng giao dịch; `DELISTING` = Hủy niêm yết; `BUYBACK` = Mua lại; `SHAREHOLDER_OPINION_POLL` = Lấy ý kiến cổ đông; `TREASURY_SHARE_SALE` = Bán cổ phiếu quỹ; `INFO_UPDATE` = Cập nhật thông tin; `OTHER_STOCK_DIVIDEND` = Trả cổ tức bằng cổ phiếu khác; `STOCK_SPLIT` = Tách cổ phiếu; `STOCK_MERGE` = Gộp cổ phiếu; `RIGHT_TO_STOCK_CONVERSION` = Chuyển quyền thành cổ phiếu; `EXCHANGE_TRANSFER` = Chuyển sàn; `VOTING_RIGHT` = Quyền bỏ phiếu; `PENDING_SHARE_TO_TRADING` = Chuyển cổ phiếu chờ giao dịch thành giao dịch; `OTC_BOND_INTEREST` = Trả lãi trái phiếu OTC. enum: - AUCTION - TRADING_SUSPENSION - DELISTING - BUYBACK - SHAREHOLDER_MEETING - SHAREHOLDER_OPINION_POLL - TREASURY_SHARE_SALE - INFO_UPDATE - OTHER_STOCK_DIVIDEND - CASH_DIVIDEND - STOCK_DIVIDEND - STOCK_SPLIT - STOCK_MERGE - RIGHTS_OFFERING - BOND_INTEREST - BOND_PRINCIPAL_INTEREST - BOND_TO_STOCK_CONVERSION - RIGHT_TO_STOCK_CONVERSION - EXCHANGE_TRANSFER - STOCK_TO_STOCK_CONVERSION - BONUS_SHARE - VOTING_RIGHT - CONVERTIBLE_BOND_OPTION - PENDING_SHARE_TO_TRADING - OTC_BOND_INTEREST - COVERED_WARRANT_SETTLEMENT example: CASH_DIVIDEND RightEventListResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - data properties: data: $ref: '#/components/schemas/RightEventList' 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 RightEventList: type: object description: Danh sách sự kiện quyền của một mã, đã phân trang. required: - symbol - pagination - events properties: symbol: type: string description: Mã cổ phiếu. example: VNM pagination: type: object properties: page: type: integer description: Trang hiện tại. example: 1 page_size: type: integer description: Số bản ghi mỗi trang. example: 20 total_items: type: integer description: Tổng số sự kiện khớp bộ lọc. example: 37 total_pages: type: integer description: Tổng số trang. example: 2 events: type: array description: Các bản ghi của trang hiện tại. items: $ref: '#/components/schemas/RightEvent' updated_at: type: - string - 'null' format: date-time description: >- Lần nguồn cập nhật gần nhất trong số các bản ghi trả về (ISO 8601 kèm offset). `null` khi không bản ghi nào mang mốc thời gian. example: '2026-05-27T14:30:15+07:00' 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 RightEvent: type: object description: >- Một sự kiện quyền của mã, mô hình common + details. `details` khớp đúng schema theo `event_type` (xem `RightEventDetails`) và `null` khi loại quyền chưa có schema riêng. required: - camast_id - event_type - symbol - dates properties: camast_id: type: string description: Mã sự kiện quyền (CAMASTID) — định danh chính. example: '0001000134011191' event_type: $ref: '#/components/schemas/RightEventType' example: CASH_DIVIDEND event_type_name: type: - string - 'null' description: Tên loại quyền. example: Cổ tức bằng tiền symbol: type: string description: Mã giao dịch chứng khoán. example: PGD description: type: - string - 'null' description: Mô tả sự kiện. dates: type: object description: >- Common chỉ giữ 2 mốc; các ngày còn lại (execution_date, begin_date, due_date...) nằm trong `details` theo từng loại quyền. properties: record_date: type: - string - 'null' format: date description: Ngày đăng ký cuối cùng / ngày chốt danh sách. ex_date: type: - string - 'null' format: date description: >- Ngày giao dịch không hưởng quyền (GDKHQ) — server tự tính = record_date lùi 1 ngày giao dịch. details: anyOf: - $ref: '#/components/schemas/RightEventDetails' - type: 'null' RightEventDetails: description: >- Field riêng theo từng loại quyền — nhánh nào áp dụng do `event_type` ở cấp gốc quyết định (bản thân `details` không lặp lại field này). `null` khi loại quyền chưa có schema riêng. oneOf: - $ref: '#/components/schemas/ShareholderMeetingDetails' - $ref: '#/components/schemas/CashDividendDetails' - $ref: '#/components/schemas/StockDividendDetails' - $ref: '#/components/schemas/RightsOfferingDetails' - $ref: '#/components/schemas/BondInterestDetails' - $ref: '#/components/schemas/BondPrincipalInterestDetails' - $ref: '#/components/schemas/BondToStockConversionDetails' - $ref: '#/components/schemas/StockToStockConversionDetails' - $ref: '#/components/schemas/BonusShareDetails' - $ref: '#/components/schemas/ConvertibleBondOptionDetails' - $ref: '#/components/schemas/CoveredWarrantSettlementDetails' ShareholderMeetingDetails: type: object description: Details của Tham dự ĐHCĐ. properties: ratio: anyOf: - $ref: '#/components/schemas/Ratio' - type: 'null' description: Tỷ lệ sở hữu → quyền biểu quyết. CashDividendDetails: type: object description: >- Details của Cổ tức bằng tiền. Có 2 case theo `rate_type`: `R` (theo %, dùng `dividend_rate`) hoặc `V` (theo giá trị đồng/CP, dùng `dividend_value`). properties: execution_date: type: - string - 'null' format: date description: Ngày thực hiện chi trả. rate_type: type: - string - 'null' enum: - R - V - null description: '`R` = theo tỷ lệ %, `V` = theo giá trị.' dividend_rate: type: - number - 'null' description: Tỷ lệ %/mệnh giá — có giá trị khi `rate_type=R`. dividend_value: type: - number - 'null' description: Đồng/cổ phiếu — có giá trị khi `rate_type=V`. StockDividendDetails: type: object description: Details của Cổ tức bằng cổ phiếu. properties: ratio: anyOf: - $ref: '#/components/schemas/Ratio' - type: 'null' description: Tỷ lệ chia cổ phiếu. RightsOfferingDetails: type: object description: Details của Quyền mua. properties: ownership_to_right_ratio: anyOf: - $ref: '#/components/schemas/Ratio' - type: 'null' description: Sở hữu → quyền. right_to_share_ratio: anyOf: - $ref: '#/components/schemas/Ratio' - type: 'null' description: Quyền → cổ phiếu được mua. subscription_price: type: - number - 'null' description: Giá mua. to_symbol: type: - string - 'null' description: Mã chứng khoán được mua. begin_date: type: - string - 'null' format: date description: Ngày bắt đầu đăng ký quyền mua. due_date: type: - string - 'null' format: date description: >- Ngày cuối cùng đăng ký quyền mua (server tự tính = hạn gốc lùi 8 ngày làm việc). BondInterestDetails: type: object description: Details của Trả lãi trái phiếu. properties: interest_rate: type: - number - 'null' description: Lãi suất (%/kỳ). interest_period: type: - number - 'null' description: Kỳ trả lãi. par_value: type: - number - 'null' description: Mệnh giá trái phiếu. BondPrincipalInterestDetails: type: object description: Details của Trả gốc và lãi trái phiếu. properties: interest_rate: type: - number - 'null' description: Lãi suất (%/kỳ). interest_period: type: - number - 'null' description: Kỳ trả lãi. par_value: type: - number - 'null' description: Mệnh giá trái phiếu. BondToStockConversionDetails: type: object description: Details của Chuyển đổi trái phiếu sang cổ phiếu. properties: conversion_ratio: anyOf: - $ref: '#/components/schemas/Ratio' - type: 'null' description: Trái phiếu → cổ phiếu. from_symbol: type: - string - 'null' description: Mã trái phiếu nguồn. to_symbol: type: - string - 'null' description: Mã giao dịch cổ phiếu đích. bond_par_value: type: - number - 'null' description: Mệnh giá trái phiếu. StockToStockConversionDetails: type: object description: Details của Chuyển đổi cổ phiếu sang cổ phiếu. properties: conversion_ratio: anyOf: - $ref: '#/components/schemas/Ratio' - type: 'null' description: Tỷ lệ chuyển đổi. to_symbol: type: - string - 'null' description: Mã giao dịch cổ phiếu đích. BonusShareDetails: type: object description: Details của Cổ phiếu thưởng. properties: ratio: anyOf: - $ref: '#/components/schemas/Ratio' - type: 'null' description: Sở hữu → cổ phiếu thưởng. ConvertibleBondOptionDetails: type: object description: Details của Chuyển đổi trái phiếu (chọn cổ phiếu hoặc tiền). properties: conversion_ratio: anyOf: - $ref: '#/components/schemas/Ratio' - type: 'null' description: Trái phiếu → cổ phiếu. right_to_share_ratio: anyOf: - $ref: '#/components/schemas/Ratio' - type: 'null' description: Quyền → cổ phiếu. conversion_price: type: - number - 'null' description: Giá chuyển đổi / giá trị nhận tiền. to_symbol: type: - string - 'null' description: Mã giao dịch cổ phiếu đích. begin_date: type: - string - 'null' format: date description: Ngày bắt đầu đăng ký. due_date: type: - string - 'null' format: date description: Ngày cuối cùng được đăng ký. CoveredWarrantSettlementDetails: type: object description: Details của Chi trả lợi tức chứng quyền. properties: settlement_price: type: - number - 'null' description: Giá thanh toán/thực hiện. payout_value: type: - number - 'null' description: Giá trị chi trả/chứng quyền. rate_type: type: - string - 'null' description: Cách biểu diễn giá trị chi trả. Ratio: type: object description: >- Tỷ lệ dạng "base/entitled" (vd "100/10"), mô hình hoá thành object để client tính trực tiếp thay vì parse chuỗi. required: - display - base - entitled properties: display: type: string description: Dạng hiển thị gốc. example: 100/10 base: type: number description: Số lượng sở hữu (vế trái). example: 100 entitled: type: number description: Số lượng được hưởng (vế phải). example: 10 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 NotFound: description: >- Tài nguyên không tồn tại — `error_code` mô tả cụ thể loại tài nguyên không tìm thấy. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: error_code: '404' message: Not found 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. ````