Skip to main content
PUT
cURL

Authorizations

X-FH-APIKEY
string
header
required

API key dài hạn của client. Cấu hình 1 lần lúc khởi tạo; có thể wire thẳng vào static setter của SDK tự-gen. Đi kèm với FINHAY_API_SECRET — secret này chỉ dùng ở phía client để tính X-FH-SIGNATURE, không bao giờ gửi qua mạng.

X-FH-TIMESTAMP
string
header
required

Unix time hiện tại tính bằng milliseconds, đưới dạng chuỗi số thập phân.

Được tính per-request bởi signing middleware. Không set thủ công — dùng middleware mẫu trong README.

X-FH-NONCE
string
header
required

UUIDv4 duy nhất per-request (ví dụ crypto.randomUUID()). Server cache cặp (apiKey, nonce) trong 5 phút; nếu nonce được reuse với cùng apiKey trong window này, request sẽ bị từ chối với AUTH_NONCE_REUSED (401).

Server chấp nhận chuỗi opaque bất kỳ về mặt kỹ thuật, nhưng nên dùng UUIDv4 để đảm bảo tính unique.

Được tính per-request bởi signing middleware. Không set thủ công — xem middleware mẫu trong tài liệu Authentication.

X-FH-SIGNATURE
string
header
required

HMAC-SHA256 của canonical signing payload, encode hex (lowercase).

Signing payload:

  • ?{QUERY} chỉ nối vào path khi request có query string.
  • {BODYHASH} là chuỗi rỗng khi body rỗng (vẫn không có newline sau đó).

Được tính per-request bởi signing middleware. Không set thủ công — dùng middleware mẫu trong README.

X-FH-BODYHASH
string
header
required

SHA-256 của raw request body, encode hex (lowercase). Bắt buộc khi request có body (POST / PUT / PATCH). Có thể bỏ qua — hoặc gửi chuỗi rỗng — khi body rỗng.

Là segment cuối của canonical signing payload ({timestamp}\n{method}\n{path}[?{query}]\n{bodyHash}). Server dùng giá trị client gửi lên để verify chữ ký; server không tự hash lại body, nên client phải hash đúng chuỗi bytes đã gửi đi.

Được tính per-request bởi signing middleware. Không set thủ công — xem middleware mẫu trong tài liệu Authentication.

X-FH-2FA-TOKEN
string
header
required

Daily 2FA session JWT do server cấp sau khi user xác thực qua OTP. Áp dụng cho các write operation nhạy cảm (đặt / sửa / huỷ lệnh) — phải đi cùng đủ 4 header HMAC + X-FH-BODYHASH.

Token có tuổi thọ 1 ngày giao dịch và được scope theo apiKey. Khi hết hạn hoặc bị revoke, server trả HTTP 403 với 1 trong các error_code:

  • OTP_SESSION_REQUIRED — chưa có session, cần khởi tạo OTP flow.
  • OTP_SESSION_EXPIRED — session đã hết hạn.
  • OTP_SESSION_INVALID — token không hợp lệ / chữ ký sai.
  • OTP_SESSION_REVOKED — bị thu hồi (user logout, đổi key, …).

Khi gặp 403 thuộc các mã trên, client phải chạy lại OTP flow để xin token mới rồi retry request.

Headers

device-id
string
required

Định danh thiết bị đặt lệnh — chuỗi định danh (device identifier) của thiết bị mà người dùng dùng để đặt / sửa / huỷ lệnh. Do client cung cấp theo mỗi request, phục vụ tuân thủ quy định giao dịch chứng khoán (lưu vết thiết bị giao dịch). Không lấy từ token / phiên xác thực.

Required string length: 1 - 64
Example:

"a1b2c3d4-5e6f-7890-abcd-ef1234567890"

Path Parameters

subAccountId
string
required

subAccountId được lấy từ bootstrap flow (GET /users/v1/users/{userId}/sub-accounts), chọn NORMAL hoặc MARGIN tuỳ mục đích.

Example:

"0001234567"

orderId
string
required

ID lệnh trên sàn — lấy từ field order_id trong response của POST /trading/oa/sub-accounts/{subAccountId}/orders (Place Order) hoặc từ GET /trading/v1/accounts/{subAccountId}/order-book (sổ lệnh trong ngày). Bắt buộc khi sửa hoặc huỷ lệnh.

Example:

"ORD123456"

Body

application/json

Body của request sửa lệnh (PUT /trading/oa/sub-accounts/{subAccountId}/orders/{orderId}). Cả 2 field đều optional nhưng phải có ít nhất 1.

Chỉ sửa được trên phần lệnh chưa khớp và khi trạng thái lệnh thuộc SENT hoặc WAITING_TO_SEND. Với lệnh đã khớp một phần, server sẽ return code = -701111 và sửa chỉ áp dụng cho phần unmatched.

quantity
integer<int64>

Số lượng mới (bội số lot size).

Required range: x >= 1
Example:

200

price
integer<int64>

Giá limit mới, đơn vị VND (không nhân 1000).

Required range: x >= 1
Example:

26000

Response

Server đã xử lý request. Phải đọc result[].code — non-null nghĩa là sàn từ chối hoặc lệnh đã khớp một phần (-701111).

Các field chung của envelope trong mọi response của Finhay API.

  • error_code"0" (string) khi thành công, mã khác "0" khi lỗi.
  • message là thông điệp ngắn từ server.
result
object[]
required

Mảng kết quả — thông thường chứa đúng 1 entry phản ánh trạng thái lệnh sau khi sửa. Khi lệnh đã khớp một phần, server có thể trả code = -701111 nghĩa là chỉ sửa được phần unmatched.

error_code
string

"0" khi thành công, khác "0" khi lỗi.

Example:

"0"

message
string

Thông điệp trạng thái dễ đọc.

Example:

"success"