> ## 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ử giao dịch theo sản phẩm

> Lịch sử giao dịch của người dùng theo từng sản phẩm, chọn bằng `type`.

| `type` | Nội dung |
|---|---|
| `stock` | Lệnh chứng khoán trên một tiểu khoản (`account`, bắt buộc); lọc một mã bằng `symbol`. |
| `haybond` | Lệnh mua/bán HayBond (không gồm HayBond Plus). |
| `haybond_plus` | Lệnh mua/bán HayBond Plus. |
| `hay0` | Nạp/rút Hay0 và Hay0 Plus; phân biệt bằng `product` (`hay0`, `hay0_plus`). |
| `fund` | Lệnh mua/bán chứng chỉ quỹ mở, gồm lệnh định kỳ; lệnh mascot hiện thành các lệnh quỹ có `detail.mascot_id`; không gồm Cho Con. |
| `child_saving` | Lệnh Cho Con của mọi hồ sơ con; `detail.child_profile` (1–3) cho biết hồ sơ. |
| `ipo` | Đăng ký mua cổ phiếu IPO; là đăng ký, không phải lệnh đã khớp. |

Khoảng ngày: bỏ trống `from` → 3 tháng trước `to`; bỏ trống `to` → hôm nay; tối đa 1 năm, bao gồm `[from, to]`.

Kết quả trả theo trang, mới nhất trước. Còn trang sau thì `next_page` khác `null`: gọi lại với `page` = `next_page`, giữ nguyên các tham số khác. Một trang có thể ít giao dịch hoặc rỗng mà vẫn còn trang sau.
`account` và `symbol` chỉ dùng với `type=stock`. Mỗi tham số chỉ truyền một lần.

Lỗi nghiệp vụ trả trong `error_code`:

| `error_code` | Khi nào |
|---|---|
| `INVALID_TRANSACTION_QUERY` | `from` sau `to`; khoảng ngày quá 1 năm, bao gồm `[from, to]`; `type=stock` thiếu `account`; `account`/`symbol` đi với `type` khác `stock`. |
| `SUB_ACCOUNT_NOT_FOUND` | Người dùng không có tiểu khoản thuộc loại `account`. |
| `TRANSACTION_HISTORY_UNAVAILABLE` | Hệ thống của sản phẩm tạm thời không trả được dữ liệu. |




## OpenAPI

````yaml /openapi.yaml get /users/v1/users/{userId}/transactions
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. Riêng
    nhóm **Lịch sử giao dịch / Danh sách yêu thích** chỉ cần `user_id`.
  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).
  - name: Lịch sử giao dịch
    description: >-
      Lịch sử giao dịch của người dùng theo sản phẩm, chọn bằng `type` — chứng
      khoán, HayBond, HayBond Plus, Hay0, chứng chỉ quỹ, Cho Con, IPO.
  - name: Danh sách yêu thích
    description: Các danh sách mã cổ phiếu yêu thích (watchlist) của người dùng.
paths:
  /users/v1/users/{userId}/transactions:
    get:
      tags:
        - Lịch sử giao dịch
      summary: Lịch sử giao dịch theo sản phẩm
      description: >
        Lịch sử giao dịch của người dùng theo từng sản phẩm, chọn bằng `type`.


        | `type` | Nội dung |

        |---|---|

        | `stock` | Lệnh chứng khoán trên một tiểu khoản (`account`, bắt buộc);
        lọc một mã bằng `symbol`. |

        | `haybond` | Lệnh mua/bán HayBond (không gồm HayBond Plus). |

        | `haybond_plus` | Lệnh mua/bán HayBond Plus. |

        | `hay0` | Nạp/rút Hay0 và Hay0 Plus; phân biệt bằng `product` (`hay0`,
        `hay0_plus`). |

        | `fund` | Lệnh mua/bán chứng chỉ quỹ mở, gồm lệnh định kỳ; lệnh mascot
        hiện thành các lệnh quỹ có `detail.mascot_id`; không gồm Cho Con. |

        | `child_saving` | Lệnh Cho Con của mọi hồ sơ con;
        `detail.child_profile` (1–3) cho biết hồ sơ. |

        | `ipo` | Đăng ký mua cổ phiếu IPO; là đăng ký, không phải lệnh đã khớp.
        |


        Khoảng ngày: bỏ trống `from` → 3 tháng trước `to`; bỏ trống `to` → hôm
        nay; tối đa 1 năm, bao gồm `[from, to]`.


        Kết quả trả theo trang, mới nhất trước. Còn trang sau thì `next_page`
        khác `null`: gọi lại với `page` = `next_page`, giữ nguyên các tham số
        khác. Một trang có thể ít giao dịch hoặc rỗng mà vẫn còn trang sau.

        `account` và `symbol` chỉ dùng với `type=stock`. Mỗi tham số chỉ truyền
        một lần.


        Lỗi nghiệp vụ trả trong `error_code`:


        | `error_code` | Khi nào |

        |---|---|

        | `INVALID_TRANSACTION_QUERY` | `from` sau `to`; khoảng ngày quá 1 năm,
        bao gồm `[from, to]`; `type=stock` thiếu `account`; `account`/`symbol`
        đi với `type` khác `stock`. |

        | `SUB_ACCOUNT_NOT_FOUND` | Người dùng không có tiểu khoản thuộc loại
        `account`. |

        | `TRANSACTION_HISTORY_UNAVAILABLE` | Hệ thống của sản phẩm tạm thời
        không trả được dữ liệu. |
      operationId: transactionsGetHistory
      parameters:
        - $ref: '#/components/parameters/UserId'
        - name: type
          in: query
          required: true
          description: Sản phẩm cần xem lịch sử (xem bảng ở mô tả endpoint).
          schema:
            type: string
            enum:
              - stock
              - haybond
              - haybond_plus
              - hay0
              - fund
              - child_saving
              - ipo
        - name: from
          in: query
          required: false
          description: >-
            Ngày bắt đầu (bao gồm), dạng `YYYY-MM-DD`. Bỏ trống → 3 tháng trước
            `to`.
          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), dạng `YYYY-MM-DD`. Không được trước `from`;
            khoảng ngày tối đa 1 năm, bao gồm `[from, to]`, ví dụ `from` là
            `2025-10-21` thì `to` chậm nhất là `2026-10-20`. Bỏ trống → hôm nay.
          schema:
            type: string
            format: date
            example: '2026-03-31'
        - name: account
          in: query
          required: false
          description: >-
            Loại tiểu khoản, chỉ dùng và bắt buộc với `type=stock`: `normal`
            (.1), `margin` (.6), `openapi` (.4).
          schema:
            type: string
            enum:
              - normal
              - margin
              - openapi
        - name: symbol
          in: query
          required: false
          description: Lọc theo một mã chứng khoán, chỉ dùng với `type=stock`.
          schema:
            type: string
            pattern: ^[A-Za-z0-9]{1,20}$
            example: FPT
        - name: page
          in: query
          required: false
          description: >-
            Trang cần đọc; truyền đúng `next_page` của trang trước. Bỏ trống →
            trang đầu.
          schema:
            type: string
      responses:
        '200':
          description: Thành công.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionHistoryResponse'
              example:
                error_code: '0'
                message: success
                data:
                  type: stock
                  from: '2026-07-13'
                  to: '2026-10-13'
                  items:
                    - product: stock
                      date: '2026-10-06'
                      side: BUY
                      asset: MBB
                      quantity: 100
                      price: 78100
                      amount: 0
                      status: EXPIRED
                      detail:
                        order_id: '8000061026000016'
                        sub_account_id: '0001001'
                        product: MBB
                        order_type: LO
                        created_at: '2026-10-06T09:15:00+07:00'
                  next_page: '2'
        '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/users/v1/users/$USER_ID/transactions?type=stock&account=normal"
components:
  parameters:
    UserId:
      name: userId
      in: path
      required: true
      description: |
        User ID. Được lấy từ bootstrap flow (`GET /users/v1/users/me`).
      schema:
        type: integer
        format: int64
        example: 123456
  schemas:
    TransactionHistoryResponse:
      allOf:
        - $ref: '#/components/schemas/EnvelopeBase'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/TransactionHistory'
    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
    TransactionHistory:
      type: object
      required:
        - type
        - from
        - to
        - items
        - next_page
      properties:
        type:
          type: string
          enum:
            - stock
            - haybond
            - haybond_plus
            - hay0
            - fund
            - child_saving
            - ipo
          description: Sản phẩm đã hỏi (`type` của request).
        from:
          type: string
          format: date
          description: Ngày bắt đầu đã áp dụng.
        to:
          type: string
          format: date
          description: Ngày kết thúc đã áp dụng.
        items:
          type: array
          description: Giao dịch của trang trong khoảng ngày, mới nhất trước.
          items:
            $ref: '#/components/schemas/TransactionItem'
        next_page:
          type:
            - string
            - 'null'
          description: Truyền vào `page` để đọc trang sau; `null` ở trang cuối.
    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
    TransactionItem:
      type: object
      description: Một giao dịch. Các field riêng của từng sản phẩm nằm trong `detail`.
      required:
        - product
        - date
        - detail
      properties:
        product:
          type: string
          enum:
            - stock
            - haybond
            - haybond_plus
            - hay0
            - hay0_plus
            - fund
            - child_saving
            - ipo
          description: Sản phẩm của giao dịch; `type=hay0` trả cả `hay0` và `hay0_plus`.
        date:
          type: string
          format: date
          description: Ngày giao dịch theo giờ Việt Nam.
        side:
          type:
            - string
            - 'null'
          description: >-
            Chiều giao dịch, giữ nguyên giá trị của nguồn (vd `BUY`/`SELL` với
            lệnh, `DEPOSIT`/`WITHDRAW` với Hay0); `null` khi nguồn không có.
        asset:
          type:
            - string
            - 'null'
          description: Mã chứng khoán, mã trái phiếu hoặc tên quỹ; `null` với Hay0.
        quantity:
          type:
            - number
            - 'null'
          description: Khối lượng (cổ phiếu, trái phiếu hoặc chứng chỉ quỹ).
        price:
          type:
            - number
            - 'null'
          description: Giá, VND.
        amount:
          type:
            - number
            - 'null'
          description: >-
            Giá trị giao dịch, VND. Lệnh chứng khoán chưa khớp trả `0`, các sản
            phẩm khác trả `null` khi chưa có giá trị (vd lệnh bán chứng chỉ quỹ
            chưa khớp).
        status:
          type:
            - string
            - 'null'
          description: Trạng thái giao dịch, giữ nguyên giá trị của nguồn.
        detail:
          type: object
          additionalProperties: true
          description: >-
            Thông tin riêng theo từng sản phẩm, giữ nguyên như hệ thống nguồn
            trả về nên có thể thay đổi, trừ `mascot_id` và `child_profile`.
  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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.