Skip to main content

Tổng quan

Kênh này cung cấp dữ liệu realtime liên quan đến tài khoản giao dịch: lệnh, sức mua, danh mục — qua Socket.IO. Đây là kênh khác với Priceboard (xem Kết nối Priceboard) và yêu cầu access token hợp lệ.
Có 2 path riêng biệt tuỳ loại sản phẩm — dùng đúng path theo tài khoản bạn đang thao tác:
  • Cổ phiếu / chứng khoán cơ sở (Underlying): eqt
  • Phái sinh (Derivatives): fno

Thông tin kết nối

Điều kiện tiên quyết

Trước khi kết nối, bạn cần có:
  1. access_token — lấy từ API đăng nhập (auth/gen-secret-key/underlying). Token phải còn hiệu lực tại thời điểm subscribe.
  2. sub_account_id (tiểu khoản) — KHÔNG phải username đăng nhập / mã custody (ví dụ 022Cxxxxxx). Đây là số tiểu khoản giao dịch thực tế, dạng ví dụ 0301001425. Dùng sai giá trị này sẽ gây lỗi FO20010 - Tiểu khoản truyền vào không hợp lệ ở các API khác và khiến subscribe realtime không nhận được dữ liệu tài khoản đúng.
Nhầm lẫn giữa mã đăng nhập (custody code) và tiểu khoản (accountId) là lỗi phổ biến nhất khi tích hợp kênh này. Nếu không chắc, hãy lấy accountId chính xác từ ứng dụng giao dịch hoặc bộ phận nghiệp vụ PHS.

Các bước kết nối

1

Đăng nhập lấy access_token

Gọi API xác thực để lấy token hợp lệ cho phiên làm việc.
2

Khởi tạo client

Kết nối tới host + path tương ứng (eqt hoặc fno), ép transport websocket.
3

Gửi subscribe

Sau sự kiện connect, gửi sự kiện get với payload chứa sub_account_idaccess_token.
4

Lắng nghe theo kênh

Server trả dữ liệu qua các sự kiện riêng theo loại nghiệp vụ — xem bảng mapping bên dưới.

Ví dụ code (Node.js / JavaScript — Underlying/EQT)

Bảng mapping kênh dữ liệu

Một số gateway cũ hơn có thể phát các event tên instrument, trade, account thay vì OM/CI/SE. Nên đăng ký lắng nghe cả hai bộ tên để tương thích ngược nếu chưa chắc chắn gateway đang dùng phiên bản nào.

Cấu trúc dữ liệu trả về

Dữ liệu tài khoản được bọc trong một wrapper chung, EVENTTYPE bên trong DT mới là giá trị xác định đây là OM, CI hay SE (không phải tên event Socket.IO ở tầng ngoài). Ví dụ thực tế — sự kiện CI (Cash Info / sức mua):

Wrapper chung (áp dụng cho mọi EVENTTYPE)

Field riêng của CI (Cash Info — Sức mua)

Các field PPREFBALDEFOVD được suy luận theo tên viết tắt, chưa được PHS xác nhận chính thức về ý nghĩa nghiệp vụ. Vui lòng đối chiếu với tài liệu nghiệp vụ nội bộ hoặc hỏi đội vận hành trước khi dùng để tính toán/hiển thị cho khách hàng.
Cấu trúc field bên trong DT cho OM (Order Management) và SE (Securities Equity) khác với CI và sẽ được bổ sung khi có mẫu dữ liệu thực tế tương ứng.

Xử lý sự cố thường gặp

Bước tiếp theo

Để nhận dữ liệu bảng giá realtime, xem Kết nối Priceboard.