Models

Các model là TypeScript interface (riêng Token và OTPResponse là class). Import từ package chính.

Cấu trúc Module

@ssi.developer/ssi-sdk
├── Auth, Data, Trading, Stream  (client classes)
├── Config                        (cấu hình)
├── models/
│   ├── auth        → Token, OTPResponse
│   ├── account     → Account
│   ├── marketData  → OHLCData, MarketIndexes, MarketIndexSummary, SecuritiesInfo, SecuritiesSummary, MasterData,
│   │                 CorporateAction
│   ├── trading     → PlaceOrderResponse, ModifyOrderResponse, CancelOrderResponse, MaxBuySellResponse,
│   │                 BatchPlaceOrderItem, BatchCancelOrderItem, BatchOrderResponse, BatchOrderResult
│   ├── portfolio   → EquityAccountBalance, DerivativeAccountBalance, EquityPosition, DerivativePosition,
│   │                 AllDerivativePosition, Order
│   ├── streaming   → DataMessage, TradingMessage, HeartbeatMessage, IndexTickMessage, IntervalMessage,
│   │                 IndexSummaryMessage, FCOOrderUpdateMessage, ...
│   └── fco         → FCOInfo, FCOParams, FCOListResponse, FCOOrder, FCOOrderBookResponse, FCOPlaceResponse,
│                     FCOCancelResponse, FCOStatusHistoryItem
├── enums/          → OrderSide, OrderType, Board, Timeframe, FCOType, FCOOperator, FCOStatus, ...
├── exceptions      → SSIError, APIError, AuthenticationError, ...
└── Trading WebSocket
                    → asyncTradingWs, tradingWs, TradingWSClient, TradingWSService, MUTATING_METHODS,
                      TradingWSResponse, FcoParamsKind, FcoListOptions, OrderBookQuery

Các nhóm theo tính năng, đều trỏ về API Services là nơi mô tả cách dùng:

• Batch Orders: BatchPlaceOrderItem, BatchCancelOrderItem, BatchOrderResponse, BatchOrderResult.
• Real-time Index Data: IndexTickMessage, IntervalMessage, IndexSummaryMessage.
• Trading WebSocket: TradingWSResponse, FcoParamsKind, FcoListOptions và OrderBookQuery.

Xác thực

Token

Ngoài field, Token còn có:

toString(), console.log và JSON.stringify của Token đều che accessToken và refreshToken. Chỉ toDict() trả giá trị thật, vì vậy đừng log kết quả của nó.

OTPResponse

Kết quả của requestOtpTyped() (xem Client Classes). OTPResponse cũng là class và che transactionId khi JSON.stringify.

Tài khoản

Account

Dữ liệu thị trường

OHLCData

MarketIndexes

MarketIndexSummary

Các field nước ngoài là undefined khi server không gửi.

SecuritiesInfo

Field số mà server bỏ trống hoặc không gửi là undefined (không phải 0). Chuỗi rỗng cũng thành undefined.

SecuritiesSummary

MasterData

Giá trần, sàn và tham chiếu của một mã, lấy từ getMasterData() (xem API Services, mục 3.6).

CorporateAction

Một sự kiện quyền (cổ tức, cổ phiếu thưởng, phát hành thêm...) của một mã, lấy từ getCorporateActions() và getCorporateActionsHistorical() (xem API Services, mục 3.7). Mọi field đều là string đúng như server trả: ngày giữ dạng text YYYY/MM/DD, ratio không được parse vì ý nghĩa phụ thuộc loại sự kiện. Field server để trống (ví dụ sự kiện mới công bố chưa có ngày giao dịch không hưởng quyền hoặc tỷ lệ) là "".

Danh mục

EquityAccountBalance

DerivativeAccountBalance

cashWithdrawableSsi và cashWithdrawableVsdc vẫn đọc được nhưng deprecated: dùng withdrawableSsi và withdrawableVsdc.

EquityPosition

DerivativePosition

AllDerivativePosition

Vị thế phái sinh của một tài khoản, tách vị thế đang mở và đã đóng. Nằm trong Position.derivative; Position.equity là danh sách EquityPosition[]. Cả hai là undefined khi tài khoản không có phần đó (xem cách các method positions trả undefined ở API Services).

Order

Response giao dịch

PlaceOrderResponse

orderId, clientRequestId, status

ModifyOrderResponse

clientModifyId, orderId, clientRequestId, status

CancelOrderResponse

clientCancelId, orderId, clientRequestId, status

MaxBuySellResponse

Tài khoản phái sinh chỉ nhận hai khối lượng. Với tài khoản đó marginRatio và purchasingPower là undefined, không phải 0. purchasePower (chuỗi, "" khi không có) vẫn đọc được nhưng deprecated: dùng purchasingPower.

Lệnh hàng loạt (Batch Orders)

Kiểu dữ liệu của placeBatchOrders và cancelBatchOrders. Cách dùng, chữ ký, idempotency và retry nằm ở API Services, mục 5.6. Giới hạn số lệnh mỗi lô xem Cấu hình và lỗi xem Xử lý lỗi.

BatchPlaceOrderItem

Một lệnh của placeBatchOrders, cùng tham số với placeOrder.

BatchCancelOrderItem

Một lệnh của cancelBatchOrders: accountNo kèm đúng một trong hai id.

BatchOrderResponse

BatchOrderResult

Lệnh điều kiện (FCO)

FCOPlaceResponse

Kết quả đặt lệnh điều kiện — fcoId

FCOCancelResponse

Kết quả huỷ lệnh điều kiện — fcoId

FCOListResponse

Danh sách lệnh điều kiện (phân trang).

FCOInfo

Thông tin chi tiết một lệnh điều kiện.

FCOParams

Tham số kích hoạt của lệnh điều kiện.

FCOOrderBookResponse

Nhật ký khớp lệnh FCO (phân trang).

FCOOrder

Nhật ký giao dịch / thực thi của lệnh FCO.

FCOStatusHistoryItem

Một lần chuyển trạng thái của lệnh FCO, trả về bởi getFcoStatusHistory(fcoId) (xem API Services, mục 5.5). Nhận danh sách rỗng khi server trả 204.

Message Streaming

DataMessage

Dữ liệu thị trường nhận qua callback onData. DataMessage là union của các kiểu sau (frame có topic mà SDK chưa có model sẽ đến dưới dạng object thô):

• TradeMessage — khớp lệnh của một mã (type: 'trade')
• IndexTickMessage — tick của chính chỉ số (xem bên dưới)
• IntervalMessage — nến 1 phút / 5 phút (xem bên dưới)
• QuoteMessage — mua/bán (type: 'quote')
• ForeignRoomMessage — room ngoại (type: 'room')
• MarketFlagMessage — cờ phiên thị trường (ATO, LO, ATC...), topic market.flag
• IndexSummaryMessage — tổng hợp chỉ số (xem bên dưới)
• MarketDataMessage — giá trần / sàn / tham chiếu của một mã, topic market.<symbol>
• MarketStatusMessage — trạng thái thị trường (market, status, tradingDate)
• PutMessage — thoả thuận (type: 'put')
• OddLotMessage — lô lẻ (type: 'oddlot')

TradingMessage

Sự kiện giao dịch nhận qua callback onTrading. TradingMessage là union của:

• OrderStatusMessage — cập nhật trạng thái lệnh thường (type: 'orderEvent')
• OrderMatchMessage — sự kiện khớp lệnh (type: 'orderMatchEvent')
• PortfolioMessage — thay đổi danh mục, chỉ tài khoản phái sinh (type: 'clientPortfolioEvent')
• FCOOrderUpdateMessage — cập nhật trạng thái lệnh điều kiện FCO (eventType: 'fcoEvent')

Event type không biết sẽ đến dưới dạng object thô.

FCOOrderUpdateMessage

Cập nhật trạng thái lệnh điều kiện FCO (streaming, nhận qua onTrading). Message này không có type: 'fcoOrderEvent': nhận diện bằng eventType (ví dụ "fcoEvent") hoặc bằng fcoId.

HeartbeatMessage

method, channel, status, message

ConnectionEvent

Sự kiện kết nối truyền vào onConnection của Stream (xem API Services, mục 6.8). Import từ package chính.

Dữ liệu chỉ số real-time

Kiểu dữ liệu của các topic chỉ số (trade.index.<code> và indexsummary.<code>). Cách subscribe, quy tắc mã chỉ số và interval nằm ở API Services, mục 6.7. Các kiểu này đến qua onData (riêng IndexSummaryMessage còn nhận được bằng onIndexSummary).

IndexTickMessage

Tick của chính chỉ số (không phải cổ phiếu thành phần), từ subscribeIndexTrade.

Field số là undefined (không phải 0) khi server không gửi. Trong các kiểu DataMessage, chỉ IndexTickMessage có field raw, nên 'raw' in msg là cách nhận diện đơn giản (xem ví dụ ở mục 6.7).

IntervalMessage

Nến 1 phút / 5 phút, nhận khi subscribe có interval là 1m hoặc 5m.

IndexSummaryMessage

Bản tổng hợp của một chỉ số, từ indexsummary.<code>.

Tài liệu public của API không liệt kê field của payload này, nên SDK không đoán và không có field kiểu sẵn. Đọc giá trị bằng indexSummaryGet(message, keys, defaultValue?): hàm trả giá trị của key đầu tiên trong keys có mặt trong message.data, hoặc defaultValue nếu không có key nào.

import { indexSummaryGet } from '@ssi.developer/ssi-sdk';

s.onIndexSummary = (msg) => {
  // 'someField' là ví dụ: thay bằng key bạn thấy trong msg.data
  const value = indexSummaryGet<number>(msg, ['someField'], 0);
  console.log(`${msg.index}: ${value}`);
};

Trading WebSocket

Các kiểu dưới đây import từ package chính @ssi.developer/ssi-sdk. Cách dùng xem API Services, mục 7.

TradingWSResponse

Kết quả của mỗi lệnh gửi qua Trading WebSocket.

Frame lỗi không trả TradingWSResponse mà ném TradingWSError (xem Xử lý lỗi).

FcoParamsKind, FcoListOptions, OrderBookQuery

Kiểu tham số của các command FCO và sổ lệnh trên Trading WebSocket.