Trading

trade-order-batch-place

Đặt nhiều lệnh mới trong một request (Batch Order).

Quy tắc chung

  • Tối đa 50 lệnh mỗi request. Các lệnh có thể thuộc nhiều tài khoản khác nhau, nhưng tất cả tài khoản phải nằm trong danh sách tài khoản được cấp quyền cho API Key.
  • Validation theo cơ chế all-or-nothing: nếu bất kỳ lệnh nào trong batch không hợp lệ, toàn bộ request bị từ chối (HTTP 400) và không có lệnh nào được thực thi.
  • Sau khi validation đạt, từng lệnh được xử lý độc lập. Một lệnh bị từ chối ở bước xử lý (ví dụ không đủ sức mua) không ảnh hưởng đến các lệnh còn lại; kết quả từng lệnh được trả về trong results (success, errorCode, errorMessage).
  • Chống replay: batchRequestTime (epoch milliseconds, UTC) phải lệch không quá 30 giây so với thời gian máy chủ.
  • Idempotency: batchRequestId phải duy nhất theo từng API Key, từng loại thao tác (đặt/hủy) trong ngày. Gửi lại cùng batchRequestId sẽ bị từ chối là request trùng lặp.
  • Chữ ký X-Signature được tính trên toàn bộ request body (cả batchRequestId, batchRequestTime và orders).
  • Mỗi lệnh trong orders áp dụng cùng quy tắc với API đặt lệnh đơn trade-order-place.

Scope yêu cầu: trading:order:post.

POST
/api/v3/trading/order/batch

Authorization

Bearer
AuthorizationBearer <token>

Nhập JWT token theo định dạng Bearer <token>.

In: header

Header Parameters

Content-Typestringrequired

Định dạng nội dung request body. Chủ yếu là application/json.

User-Agentstringoptional

Thông tin client gửi request.

Accept-Languagestringoptional

Ngôn ngữ phản hồi mong muốn. Nếu không có header này, hệ thống sẽ mặc định là en

X-Signaturestringrequired

Chữ ký RSA + SHA256 để xác thực tính toàn vẹn của request. Input bao gồm SecretKey + JSON body.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

bodyobjectrequired
batchRequestIdstringrequired

Định danh batch do client tạo ra, phải duy nhất theo từng API Key và từng loại thao tác (đặt/hủy) trong ngày. Dùng làm khóa idempotency; gửi lại cùng giá trị sẽ bị từ chối là request trùng lặp.

batchRequestTimeintegerrequired

Thời điểm client tạo batch, tính bằng epoch milliseconds (UTC). Phải lệch không quá 30 giây so với thời gian máy chủ, nếu không request bị từ chối (chống replay).

ordersarrayrequired

Danh sách lệnh cần đặt, tối đa 50 lệnh. Mỗi phần tử có cấu trúc như request của API đặt lệnh đơn.

orders[]objectrequired
clientRequestIdstring | nulloptional

Định danh lệnh do client tạo ra, dùng để đối chiếu trong các phản hồi sau này. Trường này không bắt buộc nhưng nếu có thì nên đảm bảo tính duy nhất để tránh nhầm lẫn khi xử lý phản hồi. Khi để trống thì hệ thống sẽ tự sinh định danh lệnh cho khách hàng và trả về response & streaming.

accountNostringrequired

Số tài khoản giao dịch.

symbolstringrequired

Mã chứng khoán.

sidestringrequired

Chiều mua hoặc bán của lệnh giao dịch. (B- Buy/Mua, S- Sell/Bán)

orderTypestringrequired

Loại lệnh giao dịch. (LO - Limit Order/Lệnh giới hạn, ATO - At The Open/Lệnh mở cửa, ATC - At The Close/Lệnh đóng cửa, MP - Market Price/Giá thị trường, MAK - Match and Kill, MOK - Match or Kill, MTL - Match then Limit, PLO)

quantitynumberrequired

Khối lượng đặt lệnh.

pricestringrequired

Giá đặt lệnh. Bắt buộc khi orderType là LO (Lệnh giới hạn); không bắt buộc với các loại lệnh khác (ATO, ATC, MP, MAK, MOK, MTL, PLO).

deviceIdstringrequired

Định danh thiết bị thực hiện gửi yêu cầu đặt lệnh. Thông thường dùng MAC address hoặc IMEI của thiết bị.

userAgentstringoptional

Thông tin về trình duyệt hoặc ứng dụng gửi yêu cầu.

ipAddressstringoptional

Địa chỉ IP của thiết bị gửi yêu cầu.

Response Headers

X-RATELIMIT-LIMITstringoptional

Giới hạn số request trong chu kỳ.

X-RATELIMIT-REMAININGstringoptional

Số request còn lại trong chu kỳ hiện tại.

X-RATELIMIT-RESETstringoptional

Thời điểm reset giới hạn request.

Response Body

application/json

application/json

curl -X POST "https://api.ssi.com.vn/api/v3/trading/order/batch" \  -H "Content-Type: application/json" \  -H "X-Signature: sha256=abc123..." \  -H "Content-Type: application/json" \  -d '{    "batchRequestId": "string",    "batchRequestTime": 1760400000000,    "orders": [      {        "accountNo": "string",        "symbol": "string",        "side": "B",        "orderType": "LO",        "quantity": 0.1,        "price": "string",        "deviceId": "string"      }    ]  }'

Request hợp lệ và đã được xử lý. Kết quả từng lệnh nằm trong results.

{
  "batchRequestId": "string",
  "results": [
    {
      "clientRequestId": "string",
      "orderId": "string",
      "orderStatus": "string",
      "success": true,
      "errorCode": "string",
      "errorMessage": "string"
    }
  ]
}

Yêu cầu không hợp lệ.

{
  "code": "400",
  "msg": "Invalid request"
}

trade-order-cancelDELETE

Hủy lệnh hiện có.

trade-order-batch-cancelDELETE

Hủy nhiều lệnh trong một request (Batch Order). Áp dụng cùng quy tắc chung với API đặt lệnh batch (tối đa 50 lệnh, validation all-or-nothing, chống replay 30 giây, idempotency theo `batchRequestId`, chữ ký trên toàn bộ body). Mỗi lệnh trong `orders` áp dụng cùng quy tắc với API hủy lệnh đơn `trade-order-cancel` (xác định lệnh qua `clientRequestId` hoặc `orderId`). **Scope yêu cầu:** `trading:order:delete`.