Cấu hình

Tham chiếu đầy đủ tham số Config cho Node.js SDK

Config

Config là đối tượng cấu hình trung tâm của SDK. Tạo instance với thông tin xác thực:

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

const config = new Config({
  clientId: 'YOUR_CLIENT_ID',
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  privateKey: 'YOUR_PRIVATE_KEY',
});

Tất cả tham số cấu hình

Tham số	Kiểu	Mặc định	Mô tả
`clientId`	`string`	`""`	Client ID cho portfolio operations
`apiKey`	`string`	`""`	API key từ SSI
`apiSecret`	`string`	`""`	API secret từ SSI
`privateKey`	`string`	`""`	Private key RSA để ký lệnh giao dịch (XML format, base64-encoded)
`apiUrl`	`string`	`"https://api.ssi.com.vn"`	URL REST API
`streamingUrl`	`string`	`"wss://stream.ssi.com.vn/ws/v3"`	URL WebSocket streaming
`tradingApiDomain`	`string`	theo `apiUrl`	Domain REST cho API giao dịch. Mặc định đi theo `apiUrl`. Host trần được thêm `https://`. Đọc URL cuối qua getter `config.tradingApiUrl`
`tradingWsDomain`	`string`	`"wss://api.ssi.com.vn/ws/v3/trading"`	Địa chỉ Trading WebSocket (xem bên dưới). Host trần được thêm `wss://` và path. Đọc URL cuối qua getter `config.tradingWsUrl`
`timeoutMs`	`number`	`60000`	Timeout request (ms)
`maxRetries`	`number`	`5`	Số lần retry tối đa. Chỉ áp dụng cho GET bị timeout, lệnh giao dịch (kể cả batch) không bao giờ bị retry
`retryDelayMs`	`number`	`2000`	Delay cơ sở giữa các lần retry (exponential backoff, ms)
`rateLimitPerSecond`	`number`	`10`	Giới hạn request/giây (0 = không giới hạn)
`maxBatchOrders`	`number`	`20`	Số lệnh tối đa mỗi lô Batch Orders. Giá trị không phải số nguyên từ 1 trở lên sẽ quay về mặc định
`proxy`	`string`	`undefined`	Proxy URL (HTTP hoặc SOCKS5). Không áp dụng cho WebSocket
`userAgent`	`string`	`undefined`	User-Agent gửi kèm request
`autoReconnect`	`boolean`	`true`	Tự reconnect và subscribe lại cho Stream
`otpPollIntervalMs`	`number`	`5000`	Chu kỳ poll khi chờ duyệt Smart OTP (ms)
`otpPollMaxWaitMs`	`number`	`60000`	Thời gian chờ tối đa khi poll Smart OTP (ms)
`logLevel`	`string`	`"INFO"`	Mức log: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

Mọi thời lượng đều tính bằng mili giây và có hậu tố Ms. Các tên cũ timeout và retryDelay đã đổi thành timeoutMs và retryDelayMs (đổi tên không tương thích, không có alias): truyền một option không tồn tại sẽ ném ConfigurationError. URL WebSocket (streamingUrl, tradingWsDomain) phải là wss://. Secret (apiKey, apiSecret, privateKey) bị che khi in Config, và config.toOptions() trả về bản option để dựng Config khác.

Số lệnh mỗi lô (`maxBatchOrders`)

maxBatchOrders giới hạn số lệnh mỗi lần gọi placeBatchOrders / cancelBatchOrders (và batchNewOrders / batchCancelOrders của Trading WebSocket). Lô rỗng hoặc vượt giới hạn bị từ chối ngay tại máy bằng ValidationError, chưa gửi request nào.

const config = new Config({
  clientId: 'YOUR_CLIENT_ID',
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  privateKey: 'YOUR_PRIVATE_KEY', // bắt buộc để ký batch
  maxBatchOrders: 20,
});

Lưu ý về con số 20: mã nguồn SDK ghi 20 là mặc định phía server (MaxBatchOrderCount), còn tài liệu API reference nêu tối đa 50 lệnh mỗi lô. Hai con số này chưa được đối chiếu với nhau. SDK chỉ kiểm tra giới hạn ở phía client và không hỏi server, nên server vẫn có thể từ chối một lô mà SDK cho qua. Xem cách dùng batch ở API Services.

TradingWSClientOptions

Các option của Trading WebSocket truyền qua asyncTradingWs(auth, options?), xem API Services, mục 7. Đây là tuỳ chọn của client WebSocket, không nằm trong Config. Config chỉ cấp tradingWsDomain và các giá trị mặc định cho requestTimeoutMs, userAgent.

Mọi thời lượng tính bằng mili giây và có hậu tố Ms.

Option	Kiểu	Mặc định	Mô tả
`requestTimeoutMs`	`number`	`Config.timeoutMs` (60000) qua `asyncTradingWs`; 10000 nếu tự dựng `TradingWSClient`	Thời gian chờ phản hồi của một command. Hết giờ thì ném `WebSocketError` và không retry
`signatureEncoding`	`'auto' \| 'base64' \| 'hex'`	`'auto'`	`auto` ký base64 trước, nếu chữ ký bị từ chối thì thử lại đúng một lần bằng hex
`handshakeGraceMs`	`number`	`500`	Thời gian chờ frame từ chối mà server gửi sau khi đã nhận socket
`respectRateLimit`	`boolean`	`true`	Tự chờ khi hết rate limit
`maxRateLimitWaitMs`	`number`	`2000`	Thời gian chờ tối đa mỗi lần hết rate limit
`pingIntervalMs`	`number \| null`	`30000`	Chu kỳ keep-alive. `null` hoặc `0` để tắt
`userAgent`	`string`	`Config.userAgent`	User-Agent gửi khi kết nối
`connectFn`, `clock`, `sleepFn`	functions	mặc định của SDK	Thay thế việc kết nối, đọc giờ, chờ. Dành cho test, thường không cần

Cấu hình nâng cao

Debug logging

const config = new Config({
  clientId: 'YOUR_CLIENT_ID',
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  logLevel: 'DEBUG',
});

Tuỳ chỉnh retry & rate limit

const config = new Config({
  clientId: 'YOUR_CLIENT_ID',
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  maxRetries: 3,
  retryDelayMs: 1000,
  rateLimitPerSecond: 5,
});

Proxy

const config = new Config({
  clientId: 'YOUR_CLIENT_ID',
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  proxy: 'http://proxy.example.com:8080',
});

Khuyến nghị

Lưu credentials (apiKey, apiSecret, privateKey) trong biến môi trường hoặc secret manager.
Thiếu apiKey/apiSecret sẽ gây lỗi xác thực.
Thiếu privateKey sẽ ảnh hưởng đến thao tác ký lệnh (đặt/sửa/huỷ lệnh, FCO, batch, và lệnh đổi trạng thái của Trading WebSocket).
Đặt rateLimitPerSecond theo chính sách nền tảng.
Chỉ bật logLevel: 'DEBUG' trong môi trường phát triển.
Điều chỉnh timeoutMs, maxRetries, và retryDelayMs theo workload thực tế.
proxy không áp dụng cho kết nối WebSocket (Stream và Trading WebSocket).

Trên trang này