Lệnh giao dịch

Trước khi gọi Endpoint đặt lệnh, hãy tham khảo nội dung này để hiểu đúng loại lệnh cần dùng và tránh các lỗi phổ biến khi tích hợp.

Đặc tả kỹ thuật đầy đủ (params, type, curl, code example) xem tại Endpoint Đặt lệnh.

---

​

Tổng quan

Endpoint: Các loại lệnh dùng chung một endpoint POST /accounts/:accountNo/orders

• Path Variables: accountNo là bắt buộc, lấy từ Endpoint Tài khoản giao dịch.
• Query params orderCategory và marketType dùng để phân biệt thị trường và loại lệnh giao dịch

  Params	Lệnh thường	Lệnh dừng có điều kiện	Lệnh OCO
  orderCategory	NORMAL	STOP	OCO
  marketType	STOCK / DERIVATIVE / BOND	STOCK / DERIVATIVE	DERIVATIVE

• Body request:

  Trường	NORMAL	STOP	OCO
  symbol	Required	Required	Required
  loanPackageId	Required	Required	Required
  side	Required	Required	Required
  quantity	Required	Required	Required
  orderType	Required — theo sàn	Required — LO hoặc MTL	LO
  price	Required — giá đặt lệnh	Required — giá đặt lệnh thường sẽ sinh	Required — giá đặt lệnh chốt lời
  stopPrice	—	Required — giá kích hoạt	Required — giá kích hoạt cắt lỗ
  conditionOperator	—	Required — >= hoặc <=	—
  stopOrderPrice	—	—	Required — giá đặt lệnh cắt lỗ
  durationType	—	Required — GTD	Required — DAY
  durationDateTime	—	Required — ISO 8601	—
  Lưu ý: loanPackageId: Gói vay giao dịch, xem thêm thông tin về gói vay tại đây.

​

Lệnh thường (NORMAL)

​

Vòng đời lệnh thường

Vòng đời lệnh thường mô tả các trạng thái mà một lệnh có thể đi qua kể từ lúc bạn gửi yêu cầu đến khi kết thúc.

​

Trạng thái lệnh

Trạng thái	Giải nghĩa	Chú thích
pending	Lệnh mới được tạo	Lệnh vừa gửi lên hệ thống, đang được kiểm tra và xử lý nội bộ
pendingNew	Lệnh chờ gửi lên Sở	Lệnh hợp lệ và đang chờ gửi lên hệ thống Sở giao dịch
new	Lệnh chờ khớp	Lệnh được Sở ghi nhận và đang chờ khớp theo điều kiện thị trường
partiallyFilled	Lệnh đã khớp một phần	Một phần khối lượng đã khớp, phần còn lại tiếp tục chờ khớp
filled	Lệnh khớp toàn bộ	Toàn bộ khối lượng lệnh đã được khớp thành công
pendingReplace	Lệnh chờ sửa	Yêu cầu sửa lệnh được ghi nhận, đang chờ hệ thống/Sở xử lý thay đổi
pendingCancel	Lệnh chờ hủy	Yêu cầu hủy lệnh đang chờ hệ thống/Sở xử lý
canceled	Lệnh hủy thành công	Lệnh đã được hủy thành công và không còn hiệu lực giao dịch
rejected	Lệnh bị từ chối	Lệnh không được chấp nhận do không đáp ứng điều kiện (gói vay, sức mua, hạn mức cho vay…)
expired	Lệnh hết hạn	Lệnh hết hiệu lực do kết thúc phiên hoặc quá thời gian hiệu lực mà chưa được khớp
doneForDay	Lệnh đã được giải tỏa	Lệnh kết thúc vòng đời trong ngày giao dịch

​

Loại lệnh theo sàn

Giá trị hợp lệ của orderType phụ thuộc vào sàn của mã chứng khoán:

Sàn	Loại lệnh hỗ trợ
HOSE	ATO, ATC, LO, MTL
HNX	ATC, LO, MAK, MOK, MTL, PLO
UPCOM	LO

​

Quy tắc giá và khối lượng

• quantity: Khối lượng đặt
  • Khối lượng đặt không vượt quá khối lượng tối đa có thể mua (qmaxBuy)hoặc có thể bán (qmaxSell) trên tiểu khoản giao dịch, lấy từ Endpoint /Sức mua, sức bán.
  • Với giao dịch cơ sở, khối lượng đặt là lô chẵn (100,200,…) hoặc lô lẻ (1,2,..99). Khối lượng lẻ lô (101,102,…) là không hợp lệ.
• price: Giá đặt
  • Nếu orderType=LO, giá đặt phải > 0 và phải nằm trong khoảng giá trần sàn của mã chứng khoán tại phiên giao dịch đó.
  • Nếu orderType≠LO, giá đặt truyền lên luôn = 0.

Khi lệnh khớp mua, hệ thống hình thành các vị thế Positions (hay còn gọi là danh mục tài sản) theo cặp symbol - loanPackageId. Nếu mua cùng mã nhưng khác gói vay → tạo Positions tách biệt (rủi ro được quản trị riêng).

​

Sửa lệnh

Chỉ áp dụng cho lệnh thường (orderCategory=NORMAL)

Điều kiện chung:

• Chỉ được sửa lệnh LO trong phiên giao dịch liên tục và áp dụng cho lệnh ở trạng thái Chờ khớp (New) hoặc Đã khớp một phần (PartiallyFilled)
• Giá sửa phải nằm trong biên độ trần sàn của mã chứng khoán vào phiên giao dịch đó.
• Nếu giá hoặc khối lượng sau khi sửa vượt quá sức mua /sức bán cho phép, yêu cầu sửa lệnh sẽ bị từ chối.

Sửa lệnh cơ sở:

• Khi sửa lệnh thành công, hệ thống hủy lệnh hiện tại và đặt lại một lệnh mới với thông tin đã chỉnh sửa.
• Cho phép sửa đồng thời giá và khối lượng.
• Thứ tự ưu tiên của lệnh sau khi sửa sẽ được xác định lại theo thời điểm ghi nhận sửa lệnh thành công.

Sửa lệnh phái sinh:

• Người dùng chỉ được phép sửa hoặc giá hoặc khối lượng trong một yêu cầu.
• Khối lượng sửa phải lớn hơn khối lượng đã khớp (nếu lệnh đã khớp một phần).
• Nếu khối lượng sửa lớn hơn khối lượng ban đầu, thứ tự ưu tiên của lệnh sẽ được thay đổi.

​

Lệnh STOP

Lệnh STOP là lệnh dừng có điều kiện, khi giá thị trường đạt đến mức giá kích hoạt (stopPrice), hệ thống sẽ tự động tạo một lệnh giao dịch thông thường (NORMAL) với thông số mà người dùng đã thiết lập trước và gửi lên Sở giao dịch để thực hiện khớp lệnh.

​

Phân biệt hai nhóm trường trong request

Đây là điểm dễ nhầm nhất khi tích hợp lệnh STOP. Body request chứa hai nhóm trường với ngữ nghĩa khác nhau:

Thuộc về lệnh STOP — kiểm soát điều kiện kích hoạt:

Trường	Mô tả
symbol	Mã chứng khoán
stopPrice	Giá kích hoạt lệnh
conditionOperator	>=: kích hoạt khi giá thị trường lớn hơn hoặc bằng stopPrice <=: kích hoạt khi giá thị trường nhỏ hơn hoặc bằng stopPrice
durationType	Loại thời hạn hiệu lực, chỉ nhận GTD
durationDateTime	Thời điểm hết hiệu lực theo ISO 8601. Quá thời điểm này mà lệnh chưa kích hoạt → chuyển trạng thái expired

Thuộc về lệnh thường NORMAL sẽ được sinh ra — thông số của lệnh gửi lên Sở khi kích hoạt:

Trường	Mô tả
side	Chiều mua (NB) hoặc bán (NS) của lệnh thường
orderType	Chỉ nhận LO hoặc MTL
price	Giá đặt. Nếu lệnh LO: > 0; lệnh MTL: truyền 0
quantity	Khối lượng. Quy tắc lô tương tự lệnh NORMAL
loanPackageId	Gói vay giao dịch

​

Trạng thái lệnh

Trạng thái	Giải nghĩa	Chú thích
new	Lệnh mới tạo	Lệnh STOP được tạo thành công và đang chờ điều kiện kích hoạt
activated	Đã kích hoạt	Đạt điều kiện kích hoạt, hệ thống tạo và gửi lệnh thường (NORMAL) lên Sở giao dịch
cancelled	Đã hủy	Lệnh đã hủy thành công
cancelledByRightsEvent	Hủy do sự kiện quyền	Lệnh bị hủy tự động do phát sinh sự kiện quyền của mã chứng khoán
rejected	Từ chối	Lệnh không được hệ thống chấp nhận khi tạo
failed	Kích hoạt thất bại	Điều kiện kích hoạt đã xảy ra nhưng hệ thống không thể tạo hoặc gửi lệnh NORMAL thành công
expired	Hết hiệu lực	Lệnh hết thời hạn hiệu lực và chưa được kích hoạt

Sau khi lệnh STOP chuyển sang trạng thái activated, hệ thống sẽ sinh lệnh giao dịch thông thường (NORMAL). Từ thời điểm này, lệnh NORMAL sẽ tuân theo vòng đời và trạng thái của lệnh giao dịch thông thường.

​

Lệnh OCO

Lệnh OCO (One Cancels the Other) là lệnh điều kiện kết hợp giữa chốt lời (Take Profit) và cắt lỗ (Stop Loss) trong cùng một yêu cầu đặt lệnh. Chỉ áp dụng cho phái sinh DERIVATIVE.

​

Cơ chế hoạt động:

• Người dùng gửi yêu cầu đặt lệnh OCO, hệ thống ghi nhận
• Khi lệnh OCO được kích hoạt, hệ thống gửi một lệnh thường (NORMAL) loại lệnh LO với giá chốt lời (price) lên Sở trong giờ giao dịch
• Trong thời gian lệnh LO đang chờ khớp, hệ thống tiếp tục theo dõi giá thị trường.
• Nếu giá thị trường đạt điều kiện cắt lỗ (stopPrice) trước khi lệnh LO khớp toàn bộ → hệ thống tự động sửa giá lệnh LO sang giá cắt lỗ (stopOrderPrice).
• Tại một thời điểm chỉ có một lệnh LO được gửi lên Sở giao dịch.

​

Quy tắc giá theo chiều lệnh

Trường	Lệnh mua (NB)	Lệnh bán (NS)
price — giá chốt lời	Phải < giá thị trường	Phải > giá thị trường
stopOrderPrice — giá đặt cắt lỗ	Phải > giá thị trường	Phải < giá thị trường

​

Trạng thái lệnh

Trạng thái	Giải nghĩa	Chú thích
new	Lệnh mới tạo	Lệnh OCO được tạo thành công và đang chờ điều kiện kích hoạt
activated	Đã kích hoạt	Đạt điều kiện kích hoạt, hệ thống tạo và gửi lệnh thường (NORMAL) lên Sở giao dịch
cancelled	Đã hủy	Lệnh đã hủy thành công
rejected	Từ chối	Lệnh không được hệ thống chấp nhận khi tạo
failed	Kích hoạt thất bại	Điều kiện kích hoạt đã xảy ra nhưng hệ thống không thể tạo hoặc gửi lệnh NORMAL thành công
expired	Hết hiệu lực	Lệnh hết thời hạn hiệu lực và chưa được kích hoạt