Đồng bộ Giao dịch

API này được sử dụng để đồng bộ danh sách các giao dịch chứng khoán, tiền mặt, và cổ tức cho một người dùng cụ thể từ hệ thống đối tác (Partner) vào hệ thống Simplize.

HTTP request

URL: /api/personalize/v1/partner/transaction/sync
Method: POST
Content Type: application/json
Response Type: application/json

Tham số header

Header	Mô tả	Kiểu dữ liệu	Bắt buộc
X-Api-Key	Khóa duy nhất.	string	có

Tham Số Truy Vấn (Query Parameters)

Tên Tham Số	Kiểu Dữ Liệu	Bắt buộc	Mô Tả
externalUserId	string	có	ID người dùng duy nhất từ hệ thống của đối tác.
recvWindow	string	không	Thời gian chấp nhận (ms), default: 5000
timestamp	string	có	Unix timestamp (milliseconds).
signature	string	có	HMAC-SHA256 signature.

Yêu Cầu (Request)

Request Mẫu

{
  "transactions": [
    {
      "transactionType": "STOCK_BUY",
      "partnerTransactionId": "TXN_001",
      "ticker": "HPG",
      "transactionDate": "2024-01-15T10:30:00+07:00",
      "price": 28000,
      "volume": 1000,
      "fee": 42000,
      "feeVat": 4200,
      "note": "Mua khớp lệnh"
    },
    {
      "transactionType": "CASH_DEPOSIT",
      "partnerTransactionId": "TXN_002",
      "transactionDate": "2024-01-14T09:00:00+07:00",
      "amount": 50000000,
      "note": "Nộp tiền mặt"
    },
    {
      "transactionType": "DIVIDEND_CASH",
      "partnerTransactionId": "TXN_003",
      "ticker": "HPG",
      "transactionDate": "2024-01-20T09:00:00+07:00",
      "dividendDate": "2024-01-15",
      "dividendRate": 0.1,
      "dividendCash": 100000,
      "tax": 10000,
      "volume": 1000,
      "note": "Cổ tức tiền mặt"
    }
  ]
}

Chi Tiết Tham Số Request Body

Dữ liệu được gửi lên dưới dạng JSON object với các trường sau:

Trường	Kiểu dữ liệu	Bắt buộc	Mô tả
transactions	array	có	Danh sách các giao dịch cần đồng bộ.

Các loại giao dịch (transactionType)

Mỗi phần tử trong mảng transactions đại diện cho một giao dịch. Các trường dữ liệu sẽ thay đổi tùy thuộc vào transactionType:

Loại	Mô tả
STOCK_BUY	Mua cổ phiếu
STOCK_SELL	Bán cổ phiếu
TRANSFER_IN	Chuyển cổ phiếu vào
TRANSFER_OUT	Chuyển cổ phiếu ra
DIVIDEND_CASH	Cổ tức bằng tiền
DIVIDEND_STOCK	Cổ tức bằng cổ phiếu
CASH_DEPOSIT	Nộp tiền
CASH_WITHDRAWAL	Rút tiền
OTHER_FEE	Phí khác

Chi tiết các trường dữ liệu theo loại giao dịch

1. Giao dịch Cổ phiếu (STOCK_BUY / STOCK_SELL)

Áp dụng cho mua và bán khớp lệnh trên sàn.

Trường	Kiểu	Bắt buộc	Mô tả
partnerTransactionId	string	có	Mã giao dịch duy nhất từ hệ thống đối tác (VD: VDSC-BUY-20251230-001).
ticker	string	có	Mã chứng khoán (VD: VNM). Tự động chuyển thành in hoa.
transactionDate	string	có	Ngày giờ giao dịch (Format: YYYY-MM-DDTHH:mm:ssZ).
price	number	có	Giá khớp lệnh.
volume	number	có	Khối lượng khớp lệnh.
fee	number	không	Phí giao dịch.
feeVat	number	không	Thuế VAT của phí giao dịch.
note	string	không	Ghi chú.
forceUpdate	boolean	không	Nếu true, cập nhật giao dịch đã tồn tại. Mặc định: false.

2. Chuyển nhượng Cổ phiếu (TRANSFER_IN / TRANSFER_OUT)

Áp dụng cho việc nộp/rút chứng khoán.

Trường	Kiểu	Bắt buộc	Mô tả
partnerTransactionId	string	có	Mã giao dịch duy nhất.
ticker	string	có	Mã chứng khoán.
transactionDate	string	có	Ngày giờ giao dịch.
price	number	có	Giá tham chiếu hoặc giá vốn tại thời điểm chuyển.
volume	number	có	Số lượng cổ phiếu chuyển.
note	string	không	Ghi chú.
forceUpdate	boolean	không	Nếu true, cập nhật giao dịch đã tồn tại. Mặc định: false.

3. Cổ tức bằng tiền (DIVIDEND_CASH)

Trường	Kiểu	Bắt buộc	Mô tả
partnerTransactionId	string	có	Mã giao dịch duy nhất.
ticker	string	có	Mã chứng khoán.
transactionDate	string	có	Ngày thực hiện quyền/nhận tiền.
dividendDate	string	có	Ngày đăng ký cuối cùng hoặc ngày chốt quyền (Format: YYYY-MM-DD).
dividendRate	number	có	Tỷ lệ cổ tức (VD: 0.1 cho 10%).
dividendCash	number	có	Tổng số tiền cổ tức nhận được trước thuế.
tax	number	không	Thuế thu nhập cá nhân đánh vào cổ tức.
volume	number	không	Số lượng cổ phiếu sở hữu tại ngày chốt quyền.
price	number	không	Giá (thường không bắt buộc cho cổ tức tiền).
note	string	không	Ghi chú.
forceUpdate	boolean	không	Nếu true, cập nhật giao dịch đã tồn tại. Mặc định: false.

4. Cổ tức bằng cổ phiếu (DIVIDEND_STOCK)

Trường	Kiểu	Bắt buộc	Mô tả
partnerTransactionId	string	có	Mã giao dịch duy nhất.
ticker	string	có	Mã chứng khoán.
transactionDate	string	có	Ngày nhận cổ phiếu thưởng/cổ tức.
dividendDate	string	có	Ngày chốt quyền (Format: YYYY-MM-DD).
dividendRate	number	có	Tỷ lệ thực hiện quyền.
dividendStock	number	có	Số lượng cổ phiếu nhận thêm.
volume	number	không	Số lượng cổ phiếu sở hữu tại ngày chốt quyền.
price	number	không	Giá vốn (thường là 0 hoặc điều chỉnh).
note	string	không	Ghi chú.
forceUpdate	boolean	không	Nếu true, cập nhật giao dịch đã tồn tại. Mặc định: false.

5. Giao dịch Tiền mặt (CASH_DEPOSIT / CASH_WITHDRAWAL)

Áp dụng cho nộp/rút tiền mặt vào tài khoản.

Trường	Kiểu	Bắt buộc	Mô tả
partnerTransactionId	string	có	Mã giao dịch duy nhất.
transactionDate	string	có	Ngày giờ giao dịch.
amount	number	có	Số tiền nộp/rút.
note	string	không	Ghi chú.
forceUpdate	boolean	không	Nếu true, cập nhật giao dịch đã tồn tại. Mặc định: false.

6. Phí khác (OTHER_FEE)

Trường	Kiểu	Bắt buộc	Mô tả
partnerTransactionId	string	có	Mã giao dịch duy nhất.
transactionDate	string	có	Ngày giờ phát sinh phí.
amount	number	không	Số tiền phí.
note	string	không	Ghi chú.
forceUpdate	boolean	không	Nếu true, cập nhật giao dịch đã tồn tại. Mặc định: false.

Lưu ý

partnerTransactionId phải là duy nhất trong hệ thống đối tác.
Các trường transactionDate phải tuân theo format ISO-8601.
Mã chứng khoán (ticker) sẽ tự động được chuyển thành chữ in hoa.
Khi forceUpdate là true, giao dịch có cùng partnerTransactionId sẽ được cập nhật nếu đã tồn tại.

Phản Hồi (Response)

Response Mẫu

{
  "status": 200,
  "message": "Success",
  "data": {
    "totalCount": 3,
    "successCount": 3,
    "failedCount": 0,
    "skippedCount": 0,
    "processedAt": "2026-01-13T09:07:11.927286385+07:00",
    "results": [
      {
        "partnerTransactionId": "TXN_001",
        "transactionId": 969095,
        "portfolioId": 903,
        "action": "CREATED",
        "processedAt": "2026-01-13T09:07:11+07:00",
        "warnings": []
      },
      {
        "partnerTransactionId": "TXN_002",
        "transactionId": 969096,
        "portfolioId": 903,
        "action": "CREATED",
        "processedAt": "2026-01-13T09:07:11+07:00",
        "warnings": []
      },
      {
        "partnerTransactionId": "TXN_003",
        "transactionId": 969097,
        "portfolioId": 903,
        "action": "CREATED",
        "processedAt": "2026-01-13T09:07:11+07:00",
        "warnings": []
      }
    ]
  }
}

Chi Tiết Tham Số Response

Tên Thuộc Tính	Kiểu Dữ Liệu	Mô Tả
status	number	Mã trạng thái HTTP. 200 nghĩa là yêu cầu hợp lệ.
message	string	Thông báo kết quả.
data.totalCount	number	Tổng số giao dịch được gửi lên.
data.successCount	number	Số lượng giao dịch đồng bộ thành công.
data.failedCount	number	Số lượng giao dịch đồng bộ thất bại.
data.skippedCount	number	Số lượng giao dịch bị bỏ qua.
data.processedAt	string	Thời gian xử lý request (ISO-8601).
data.results	array (Xem chi tiết)	Danh sách kết quả chi tiết của từng giao dịch.

Cấu trúc thuộc tính results

Quay lại

Tên Thuộc Tính	Kiểu Dữ Liệu	Mô Tả
partnerTransactionId	string	Mã giao dịch từ hệ thống đối tác.
transactionId	number	ID giao dịch trong hệ thống Simplize.
portfolioId	number	ID danh mục đầu tư liên kết.
action	string	Hành động đã thực hiện: CREATED, UPDATED, SKIPPED.
processedAt	string	Thời gian xử lý giao dịch (ISO-8601).
warnings	array	Danh sách các cảnh báo (nếu có).

Shell
Node
PHP
Python
Go
Java
CREDENTIALS▼Environment:
X-Api-Key:
Secret Key:
* Timestamp và Signature sẽ được tự động tạo khi gọi API
REQUEST
PARAMS
RESPONSE200{
  "status": 200,
  "message": "Success",
  "data": {
    "totalCount": 2,
    "successCount": 2,
    "failedCount": 0,
    "skippedCount": 0,
    "processedAt": "2026-01-13T09:07:11.927286385+07:00",
    "results": [
      {
        "partnerTransactionId": "TXN_001",
        "transactionId": 969095,
        "portfolioId": 903,
        "action": "CREATED",
        "processedAt": "2026-01-13T09:07:11+07:00",
        "warnings": []
      },
      {
        "partnerTransactionId": "TXN_002",
        "transactionId": 969096,
        "portfolioId": 903,
        "action": "CREATED",
        "processedAt": "2026-01-13T09:07:11+07:00",
        "warnings": []
      }
    ]
  }
}

HTTP request​

Tham số header​

Tham Số Truy Vấn (Query Parameters)​

Yêu Cầu (Request)​

Request Mẫu​

Chi Tiết Tham Số Request Body​

Các loại giao dịch (transactionType)​

Chi tiết các trường dữ liệu theo loại giao dịch​

1. Giao dịch Cổ phiếu (STOCK_BUY / STOCK_SELL)​

2. Chuyển nhượng Cổ phiếu (TRANSFER_IN / TRANSFER_OUT)​

3. Cổ tức bằng tiền (DIVIDEND_CASH)​

4. Cổ tức bằng cổ phiếu (DIVIDEND_STOCK)​

5. Giao dịch Tiền mặt (CASH_DEPOSIT / CASH_WITHDRAWAL)​

6. Phí khác (OTHER_FEE)​

Phản Hồi (Response)​

Response Mẫu​

Chi Tiết Tham Số Response​

Cấu trúc thuộc tính results​

CREDENTIALS▼

REQUEST

PARAMS

RESPONSE200