Models

Tất cả model nằm trong namespace SsiSdk.Models, là các sealed class (hoặc record) với auto-property:

using SsiSdk.Models;

Quy ước chung từ 3.3.x: tiền và giá là decimal (không dùng double); trường server có thể không gửi thì là kiểu nullable (int?, decimal?, string?) và là null khi vắng mặt.

Xác thực

Token

ToString() của Token che AccessToken và RefreshToken.

OtpResponse

Kết quả của RequestOtpTypedAsync().

Account

Account

Market Data

OhlcData

MarketIndexes

MarketIndexSummary

SecuritiesInfo

SecuritiesSummary

MasterData

CorporateAction

Mỗi trường là chuỗi đúng như server trả: ngày giữ nguyên dạng YYYY/MM/DD, Ratio không được ép kiểu vì ý nghĩa phụ thuộc loại sự kiện. Trường server để trống hoặc không gửi là "" (không phải null).

Method trả về model này: GetCorporateActionsAsync, GetCorporateActionsHistoricalAsync (mục 3.7 của API Services).

DownloadData không còn trong SDK: các hàm Download* ném NotImplementedException.

Portfolio

EquityAccountBalance

DerivativeAccountBalance

CashWithdrawableSSI và CashWithdrawableVSDC là tên cũ, được đánh dấu [Obsolete]; dùng WithdrawableSSI và WithdrawableVSDC.

EquityPosition

DerivativePosition

AllDerivativePosition

Position

Vị thế của một tài khoản; phần nào server không trả về thì là null.

Order

OrderBook

Các lệnh của một tài khoản cùng tổng số bản ghi do server báo.

EquityPPMMR / DerivativePPMMR

Hai model chứa rất nhiều chỉ số ký quỹ chi tiết (margin ratio, limit, collateral, ...), tất cả là decimal. Các trường thường dùng nhất:

Trading Responses

PlaceOrderResponse

OrderId, ClientRequestId, Status — đều string.

ModifyOrderResponse

ClientModifyId, OrderId, ClientRequestId, Status — đều string.

CancelOrderResponse

ClientCancelId, OrderId, ClientRequestId, Status — đều string.

MaxBuySellResponse

PurchasePower (kiểu string) là tên cũ, được đánh dấu [Obsolete]; dùng PurchasingPower.

Models lệnh hàng loạt (Batch)

Các model dùng cho PlaceBatchOrdersAsync và CancelBatchOrdersAsync (REST) và cho batch qua Trading WebSocket. Method, giới hạn, cách hoạt động và ví dụ nằm ở mục 5.6 của API Services; trang này chỉ liệt kê cấu trúc.

Giới hạn số lệnh mỗi batch là Config.MaxBatchOrders (mặc định 20). API reference ghi giới hạn phía server là 50, chưa đối chiếu được với server thật; việc nâng MaxBatchOrders do bên gọi quyết định.

BatchPlaceOrderItem

record với các tham số giống PlaceOrderAsync.

BatchCancelOrderItem

Mỗi item hủy cần đúng một trong OrderId hoặc ClientRequestId, nếu không sẽ ném ValidationException.

BatchOrderResponse

BatchOrderResult

Luôn kiểm tra Success của từng phần tử trong Results: một lệnh bị từ chối không làm ném exception.

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

FcoPrice

Trường giá của lệnh điều kiện: một số (100.5m, 25000) hoặc một từ loại lệnh ("MP", OrderType.MTL). Chuỗi được gửi nguyên văn. Có chuyển đổi ngầm từ decimal, int, long và string. Với các từ thị trường (ATO, ATC, MTL, MP, MOK, MAK), độ trượt giá (slip) không được áp dụng.

FCOPlaceResponse

Kết quả đặt lệnh điều kiện — FCOID (string).

FCOCancelResponse

Kết quả huỷ lệnh điều kiện — FCOID (string).

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. Giá trị chưa đặt là null.

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.

Models streaming

Message streaming là các sealed class trong SsiSdk.Models. Chúng đến qua SetOnData / OnData (dữ liệu thị trường) và SetOnTrading (sự kiện giao dịch) dưới dạng object: kiểm tra kiểu bằng pattern matching. Frame mà SDK không có model tương ứng được giữ nguyên là JsonElement. Cách subscribe nằm ở mục 6 của API Services.

Parser chọn model theo topic của frame dữ liệu:

Sự kiện giao dịch được chọn theo eventType: orderEvent là OrderStatusMessage, orderMatchEvent là OrderMatchMessage, clientPortfolioEvent là PortfolioMessage, fcoEvent là FCOOrderUpdateMessage. Khi không có eventType, topic order.* được coi là OrderStatusMessage và portfolio.* là PortfolioMessage.

Chưa xác nhận: SDK chỉ ánh xạ khoá server sang thuộc tính. Ý nghĩa chính xác của từng trường tick (đơn vị, có cộng dồn trong phiên hay không, ví dụ Value, TotalMatchQuantity, và các trường Open/High/Low/Avg của TradeMessage) chưa được xác nhận với server thật. Dùng Raw hoặc Data khi cần đối chiếu, và đừng dùng làm căn cứ cho logic quan trọng khi chưa kiểm chứng.

HeartbeatMessage

Method, Channel, Status, Message — đều string.

TradeMessage

IndexTickMessage

Tick của chính chỉ số, từ trade.index.CODE.

Trường số là null khi server không gửi. Dùng Raw cho các khóa SDK chưa ánh xạ. Cột "Mô tả" là tên theo SDK, chưa xác nhận với server (xem lưu ý ở đầu mục).

IntervalMessage

Nến, từ trade.CODE@1m / @5m hoặc trade.index.CODE@1m / @5m.

IndexSummaryMessage

Từ indexsummary.CODE.

API reference liệt kê các khóa của tổng hợp chỉ số: s, b, ss, t, v, c, cr, adv, dec, nc, ce, fl, tmv, tmq, tvp, tqp, tq, tv, với ý nghĩa như bảng tick ở trên. tq bằng tmq cộng tqp, và tv bằng tmv cộng tvp.

stream.Streaming.OnIndexSummary = m =>
{
    // Get trả về khóa đầu tiên có mặt (một JsonElement), hoặc null
    Console.WriteLine($"{m.Index}: v={m.Get("v")} ({m.Data.Count} trường)");
};

QuoteMessage

MarketStatusMessage

Market, Status, TradingDate — đều string.

MarketFlagMessage

Cờ phiên thị trường (ATO, LO, ATC, ...), từ topic market.flag.

MarketDataMessage

Dữ liệu tham chiếu (trần, sàn, tham chiếu) của một mã, từ market.SYMBOL.

ForeignRoomMessage

Type, TradingTime, Symbol (string); TotalRoom, CurrentRoom, BuyQuantity, SellQuantity (int); BuyValue, SellValue (long).

PutMessage

Type, TradingTime, Symbol (string); Price (decimal); Quantity, TotalQuantity (int); TotalValue (long).

OddLotMessage

Type, TradingTime, Symbol (string); Price (decimal); Quantity (int); BidPrices, AskPrices (List<decimal>); BidVolumes, AskVolumes (List<int>).

OrderStatusMessage

Cập nhật trạng thái lệnh (orderEvent, topic order.<accountNo>).

OrderMatchMessage

Một lần khớp của lệnh (orderMatchEvent).

PortfolioMessage

Cập nhật vị thế (clientPortfolioEvent, chỉ tài khoản phái sinh). Số liệu server không gửi là null.

TotalAsset, CashBalance, StockValue còn trong class nhưng đã deprecated: server không bao giờ gửi nên luôn là null.

FCOOrderUpdateMessage

Cập nhật trạng thái lệnh điều kiện FCO, nhận qua SetOnTrading khi eventType là "fcoEvent". Không có topic fco_order.* hay fco.* nào được parse riêng.

Chưa xác nhận: code SDK parse fcoEvent, nhưng CHANGELOG của SDK liệt kê streaming fcoEvent là chưa triển khai. Chưa kiểm chứng với server thật; đừng dựa vào luồng này cho logic quan trọng.

ConnectionEvent

record ConnectionEvent(string State, int ReconnectCount = 0, Exception? Error = null), nhận qua OnConnection. State là một trong các hằng của ConnectionState: "connected", "reconnected", "disconnected", "failed". ReconnectCount là số lần kết nối lại; Error là exception đi kèm khi có.

TradingWsResponse

Frame thành công từ Trading WebSocket (namespace SsiSdk, không phải SsiSdk.Models). Xem mục 7 của API Services.

Khác

RateLimitInfo

record RateLimitInfo(int? Limit, int? Remaining): thông tin rate limit của response gần nhất, đọc qua auth.RateLimit.