ping_pong
Client có thể chủ động gửi method: "ping_pong" (hoặc "ping_only") bất kỳ lúc nào để kiểm tra
kết nối còn sống; server trả ack ngay lập tức trên channel HEARTBEAT. Message này không cần
chữ ký và không mang id.
Client gửi ping:
{ "method": "ping_pong" }
Server trả pong:
{ "method": "ping_pong", "channel": "HEARTBEAT", "status": "ok", "message": "pong" }
Server cũng tự động phát một message heartbeat định kỳ (mỗi 30 giây) cho mọi kết nối đang mở — client không bắt buộc phải tự gửi ping, nhưng nên làm vậy để phát hiện sớm khi kết nối bị treo.
Response Body
application/json
Sample Request
wscat -c wss://api.ssi.com.vn/ws/v3/trading -x '{
"method": "ping_pong"
}'Sample Response
{
"method": "ping_pong",
"channel": "HEARTBEAT",
"status": "ok",
"message": "pong"
}Kết nối WebSocket APIWS
Thiết lập kết nối WebSocket bằng HTTP Upgrade request tới `/ws/v3/trading`. Server trả `HTTP 101 Switching Protocols` khi kết nối thành công. Xác thực: truyền JWT access token qua một trong hai cách (ưu tiên theo thứ tự): - Query string: `wss://api.ssi.com.vn/ws/v3/trading?token=<jwt>` - Header: `Authorization: Bearer <jwt>` **Giới hạn kết nối:** tối đa 10 kết nối đồng thời cho mỗi API Key; vượt hạn mức bị từ chối với lý do `Connection limit exceeded`. **⚠️ Lưu ý khi implement client:** trừ trường hợp request không phải WebSocket upgrade hợp lệ (trả `400` thật trước khi kết nối), **mọi lý do từ chối khác (401/403/429) đều xảy ra SAU KHI đã kết nối thành công (HTTP 101)** — server nhận kết nối trước, gửi một message mô tả lý do, rồi mới đóng kết nối. Lý do: hầu hết thư viện WebSocket client không hiển thị được HTTP status code của bước kết nối. Client **nên đọc message đầu tiên** sau khi connect để biết kết nối có thực sự sẵn sàng gửi lệnh hay không. **Ví dụ message từ chối:** ```json { "code": 401, "msg": "Invalid or expired token" } ``` Các lý do từ chối có thể gặp: `401` token thiếu/sai/hết hạn/bị thu hồi, `403` thiếu quyền `tradingws:*:*`, `429` vượt giới hạn kết nối đồng thời, `500` lỗi hệ thống.
order.placeWS
Đặt lệnh mới. Hệ thống **phản hồi ngay** (`orderStatus: "PD"`) để xác nhận đã nhận lệnh — trạng thái khớp lệnh thật sẽ đến sau qua kênh thông báo `order.{accountNo}` (xem mục "Đặt/sửa/hủy lệnh: xác nhận nhanh, kết quả đến sau" ở đầu tài liệu). Yêu cầu chữ ký `signature` (RSA+SHA256) theo quy định UBCKNN về toàn vẹn dữ liệu giao dịch. Scope bắt buộc: `tradingws:order:post`.