> ## 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. # Quyền cổ đông của tiểu khoản > 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. ## OpenAPI ````yaml /openapi.yaml get /trading/v5/account/{subAccountId}/user-rights openapi: 3.1.0 info: title: Finhay Securities Open API version: 0.2.0-preview.2 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: Dữ liệu giao dịch description: >- Giá stock realtime và lịch sử OHLCV (dạng columnar, phục vụ charting / time-series). - 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, …) và lãi suất tiền gửi ngân hàng. - name: Hàng hoá description: >- Hàng hoá và tài sản thay thế — vàng, bạc (spot / chart / theo nhà cung cấp) và crypto trending. - name: Tổng hợp đa loại description: >- Endpoint composite tổng hợp cross-domain (vàng / bạc / crypto / FX / lãi suất / US index) trong 1 call. Nên dùng endpoint chuyên biệt nếu chỉ cần 1 loại. - name: Quỹ mở description: >- Quỹ mở (open-ended funds) — danh sách quỹ, công ty quản lý, NAV history, holdings, ranking và benchmark cross-fund. - 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: /trading/v5/account/{subAccountId}/user-rights: get: tags: - Quyền cổ đông summary: Quyền cổ đông của tiểu khoản description: | 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. operationId: rightsGetUserRights parameters: - $ref: '#/components/parameters/SubAccountId' responses: '200': description: >- Trả về `result` mảng các quyền cổ đông của tiểu khoản, sort theo `reportDate` giảm dần. content: application/json: schema: $ref: '#/components/schemas/UserRightsResponse' example: error_code: '0' message: success result: - accountId: '0001234567' depositoryNumber: '0123456' fullName: Nguyen Van A ownNumberOfShare: 1000 ratio: '1:1' status: COMPLETED userRightRegisterStatus: RECEIVED caMastId: CAM987 amount: 1000000 symbol: VNM toSymbol: null numberOfWaitingStock: 0 waitingAmountForReturn: 0 rightOffRate: '0' buyPrice: 0 allowRegister: false totalStocksCanBuy: 0 totalPayAmount: 0 startDate: '2024-03-01' finishDate: '2024-03-31' startDateTransfer: '2024-03-05' actionDate: '2024-03-15' finishDateTransfer: '2024-03-20' reportDate: '2024-03-15' type: CASH_DIVIDEND stockName: CTCP Sữa Việt Nam totalVolume: 0 totalValue: 0 referencePrice: 72000 closePrice: 72500 ceilingPrice: 77500 floorPrice: 67500 predictPrice: 0 changePrice: 500 hasRead: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - FinhayApiKey: [] FinhayTimestamp: [] FinhayNonce: [] FinhaySignature: [] x-codeSamples: - lang: bash label: cURL source: | curl \ -H "X-FH-APIKEY: $FINHAY_API_KEY" \ -H "X-FH-TIMESTAMP: $TIMESTAMP_MS" \ -H "X-FH-NONCE: $NONCE_UUID" \ -H "X-FH-SIGNATURE: $SIGNATURE_HEX" \ "https://open-api.fhsc.com.vn/trading/v5/account/$SUB_ACCOUNT_NORMAL/user-rights" components: parameters: SubAccountId: name: subAccountId in: path required: true description: | subAccountId được lấy từ bootstrap flow (`GET /users/v1/users/{userId}/sub-accounts`), chọn NORMAL hoặc MARGIN tuỳ mục đích. schema: type: string example: '0001234567' schemas: UserRightsResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - result properties: result: type: array items: $ref: '#/components/schemas/UserRight' 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 UserRight: type: object description: 1 quyền cổ đông của tiểu khoản. properties: accountId: type: string depositoryNumber: type: string fullName: type: string ownNumberOfShare: type: integer format: int64 description: Number of shares owned at record date. ratio: type: string description: Right ratio (e.g. `1:5`). status: $ref: '#/components/schemas/UserRightStatus' userRightRegisterStatus: $ref: '#/components/schemas/UserRightRegisterStatus' caMastId: type: string description: Corporate action master ID. amount: type: integer format: int64 symbol: type: string example: VNM toSymbol: type: - string - 'null' description: Target symbol (for stock-conversion events). numberOfWaitingStock: type: integer format: int64 waitingAmountForReturn: type: integer format: int64 rightOffRate: type: string description: Right offering rate. buyPrice: type: integer format: int64 description: Subscription price (for stock rights). allowRegister: type: boolean description: Whether registration is allowed. totalStocksCanBuy: type: integer format: int64 totalPayAmount: type: integer format: int64 startDate: type: string format: date finishDate: type: string format: date startDateTransfer: type: string format: date actionDate: type: string format: date description: Record date / ex-date. finishDateTransfer: type: string format: date reportDate: type: string format: date description: Used for sorting (descending). type: $ref: '#/components/schemas/UserRightType' stockName: type: string totalVolume: type: integer format: int64 totalValue: type: integer format: int64 referencePrice: type: integer format: int64 closePrice: type: integer format: int64 ceilingPrice: type: integer format: int64 floorPrice: type: integer format: int64 predictPrice: type: integer format: int64 changePrice: type: integer format: int64 hasRead: type: boolean description: Whether the user has read this right notification. 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 UserRightStatus: type: string description: | Trạng thái xử lý quyền cổ đông (phía hệ thống). | Giá trị | Ý nghĩa | |---------|---------| | `WAIT_FOR_REVIEW` | Chờ review | | `WAIT_EXECUTED` | Chờ thực hiện | | `WAITING_FOR_APPROVE` | Chờ phê duyệt | | `NAVIGATING` | Chuyển sang bước kế tiếp | | `COMPLETED` | Đã hoàn tất | | `ALLOCATION_COMPLETED` | Đã phân bổ xong | | `CANCELED` | Đã huỷ | | `EMPTY_STOCK` | Không còn stock để phân bổ | | `APPROVED` | Đã phê duyệt | | `REJECTED` | Từ chối | | `READY_FOR_TRADE` | Sẵn sàng giao dịch | | `READY_FOR_CLOSE` | Sẵn sàng đóng | | `STOCK_ALLOTTED` | Đã chia stock | | `MONEY_ALLOTTED` | Đã chia tiền | | `PARTIALLY_DONE` | Hoàn tất 1 phần | | `VERIFIED` | Đã xác nhận | | `DELETED` | Đã xoá | | `REGISTERED` | Đã đăng ký | | `UNKNOWN` | Không xác định / fallback | enum: - WAIT_FOR_REVIEW - WAIT_EXECUTED - WAITING_FOR_APPROVE - NAVIGATING - COMPLETED - ALLOCATION_COMPLETED - CANCELED - EMPTY_STOCK - APPROVED - REJECTED - READY_FOR_TRADE - READY_FOR_CLOSE - STOCK_ALLOTTED - MONEY_ALLOTTED - PARTIALLY_DONE - VERIFIED - DELETED - REGISTERED - UNKNOWN x-enum-varnames: - WAIT_FOR_REVIEW - WAIT_EXECUTED - WAITING_FOR_APPROVE - NAVIGATING - COMPLETED - ALLOCATION_COMPLETED - CANCELED - EMPTY_STOCK - APPROVED - REJECTED - READY_FOR_TRADE - READY_FOR_CLOSE - STOCK_ALLOTTED - MONEY_ALLOTTED - PARTIALLY_DONE - VERIFIED - DELETED - REGISTERED - UNKNOWN UserRightRegisterStatus: type: string description: | Trạng thái đăng ký quyền cổ đông (phía user). | Giá trị | Ý nghĩa | |---------|---------| | `UNREGISTER` | Chưa đăng ký | | `REGISTERED` | Đã đăng ký | | `EXPIRED` | Hết hạn đăng ký | | `RECEIVED` | Đã nhận quyền | | `PARTIAL_REGISTERED` | Đăng ký 1 phần | | `PENDING` | Đang xử lý | | `PARTIAL_RECEIVED` | Đã nhận 1 phần | | `WAIT_REGISTER` | Đang chờ đăng ký | | `REGISTERED_V2` | Đã đăng ký (schema v2) | | `WAIT_RECEIVE` | Đang chờ nhận | | `WAIT_STOCK` | Đang chờ phân bổ stock | | `PARTIAL_RECEIVED_V2` | Đã nhận 1 phần (schema v2) | | `UNKNOWN` | Không xác định / fallback | enum: - UNREGISTER - REGISTERED - EXPIRED - RECEIVED - PARTIAL_REGISTERED - PENDING - PARTIAL_RECEIVED - WAIT_REGISTER - REGISTERED_V2 - WAIT_RECEIVE - WAIT_STOCK - PARTIAL_RECEIVED_V2 - UNKNOWN x-enum-varnames: - UNREGISTER - REGISTERED - EXPIRED - RECEIVED - PARTIAL_REGISTERED - PENDING - PARTIAL_RECEIVED - WAIT_REGISTER - REGISTERED_V2 - WAIT_RECEIVE - WAIT_STOCK - PARTIAL_RECEIVED_V2 - UNKNOWN UserRightType: type: string description: | Loại quyền cổ đông. | Giá trị | Ý nghĩa | |---------|---------| | `OTC_BOND_INTEREST` | Trả lãi trái phiếu OTC | | `SHAREHOLDER_MEETING` | Họp đại hội cổ đông | | `SOLICIT_SHAREHOLDER_OPINIONS` | Lấy ý kiến cổ đông bằng văn bản | | `CASH_DIVIDEND` | Cổ tức tiền mặt | | `STOCK_DIVIDEND` | Cổ tức bằng stock | | `STOCK_RIGHT` | Phát hành quyền mua stock | | `BOND_INTEREST` | Trả lãi trái phiếu | | `BOND_PRINCIPAL_AND_INTEREST` | Trả gốc + lãi trái phiếu | | `CONVERT_BONDS_TO_STOCKS` | Chuyển đổi trái phiếu sang stock | | `CONVERT_STOCKS_TO_OTHER_STOCKS` | Chuyển đổi stock sang stock khác | | `BONUS_SHARES` | Thưởng stock | | `VOTING_RIGHTS` | Quyền biểu quyết | | `CONVERTIBLE_BOND` | Sự kiện trái phiếu chuyển đổi | | `TRANSFER_PENDING_STOCKS` | Chuyển stock đang chờ | | `WARRANT_DIVIDENDS` | Cổ tức chứng quyền | enum: - OTC_BOND_INTEREST - SHAREHOLDER_MEETING - SOLICIT_SHAREHOLDER_OPINIONS - CASH_DIVIDEND - STOCK_DIVIDEND - STOCK_RIGHT - BOND_INTEREST - BOND_PRINCIPAL_AND_INTEREST - CONVERT_BONDS_TO_STOCKS - CONVERT_STOCKS_TO_OTHER_STOCKS - BONUS_SHARES - VOTING_RIGHTS - CONVERTIBLE_BOND - TRANSFER_PENDING_STOCKS - WARRANT_DIVIDENDS x-enum-varnames: - OTC_BOND_INTEREST - SHAREHOLDER_MEETING - SOLICIT_SHAREHOLDER_OPINIONS - CASH_DIVIDEND - STOCK_DIVIDEND - STOCK_RIGHT - BOND_INTEREST - BOND_PRINCIPAL_AND_INTEREST - CONVERT_BONDS_TO_STOCKS - CONVERT_STOCKS_TO_OTHER_STOCKS - BONUS_SHARES - VOTING_RIGHTS - CONVERTIBLE_BOND - TRANSFER_PENDING_STOCKS - WARRANT_DIVIDENDS 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. FinhayTimestamp: type: apiKey in: header name: X-FH-TIMESTAMP description: > Unix time hiện tại tính bằng **milliseconds**, đưới dạng chuỗi số thập phân. Được tính per-request bởi signing middleware. **Không** set thủ công — dùng middleware mẫu trong README. FinhayNonce: type: apiKey in: header name: X-FH-NONCE description: | UUIDv4 duy nhất per-request (ví dụ `crypto.randomUUID()`). Server cache cặp `(apiKey, nonce)` trong 5 phút; nếu nonce được reuse với cùng apiKey trong window này, request sẽ bị từ chối với `AUTH_NONCE_REUSED` (401). Server chấp nhận chuỗi opaque bất kỳ về mặt kỹ thuật, nhưng nên dùng UUIDv4 để đảm bảo tính unique. Được tính per-request bởi signing middleware. **Không** set thủ công — xem middleware mẫu trong tài liệu Authentication. FinhaySignature: type: apiKey in: header name: X-FH-SIGNATURE description: > HMAC-SHA256 của canonical signing payload, encode hex (lowercase). Signing payload: ``` {X-FH-TIMESTAMP}\n{METHOD}\n{REQUEST_PATH}[?{QUERY}]\n{BODYHASH} ``` - `?{QUERY}` chỉ nối vào path khi request có query string. - `{BODYHASH}` là chuỗi rỗng khi body rỗng (vẫn không có newline sau đó). Được tính per-request bởi signing middleware. **Không** set thủ công — dùng middleware mẫu trong README. ````