Lấy tỷ giá FX

Lấy tỷ giá ngoại hối (hai chiều bid/ask) cho Merchant yêu cầu.

API hỗ trợ ba chế độ tra cứu:

• Một cặp — lấy tỷ giá của một cặp tiền tệ duy nhất.
• Nhiều cặp — lấy tỷ giá của một danh sách cặp cụ thể.
• Tất cả các cặp — lấy tỷ giá của mọi cặp được hỗ trợ cho Merchant.

Mỗi tỷ giá được trả về đi kèm với quote_code, thời gian last_updated (tính tươi) và thời gian valid_until (tính hợp lệ).

Đường dẫn

• URL: /cb-core/api/v1/fx/get-rate
• Method: POST
• Mô tả: Lấy tỷ giá bid/ask cho một, nhiều hoặc tất cả các cặp tiền tệ.

Request

Bảng Request

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
request_id	string(50)	Có	Mã duy nhất định danh request. Định dạng gợi ý: MerchantCode + BK + YYYYMMDD + UniqueId
request_time	string(19)	Có	Thời gian Merchant gửi request. Định dạng: YYYY-MM-DD HH:MM:SS
merchant_code	string(20)	Có	Mã merchant được Baokim cung cấp trước khi tích hợp
type	int(1)	Có	Chế độ tra cứu. 1: một cặp, 2: nhiều cặp, 3: tất cả các cặp được hỗ trợ
currency_pair	string(255)	Có điều kiện	Cặp tiền tệ cần tra cứu. Khi type = 1: một cặp duy nhất, ví dụ USD/VND. Khi type = 2: danh sách được ngăn cách bằng dấu phẩy, ví dụ USD/VND,CNY/VND. Khi type = 3: không bắt buộc.

Ví dụ Request

{
  "request_id": "MERCHANT1234BK202606052",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "type": 2,
  "currency_pair": "USD/VND,CNY/VND"
}

Response

Bảng Response

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
response_code	int(4)	Có	Mã kết quả từ Baokim, theo bảng Mã lỗi
response_message	string(200)	Có	Mô tả mã kết quả
merchant_code	string(20)	Có	Mã merchant được Baokim cung cấp trước khi tích hợp
data	Array of Objects	Có	Danh sách báo giá tỷ giá, một cho mỗi cặp yêu cầu

Cấu trúc mảng Data (bên trong data)

Tham số	Loại dữ liệu	Mô tả
currency_pair	string(10)	Cặp tiền tệ ở định dạng BASE/QUOTE (ví dụ USD/VND)
bid	decimal(18,4)	Tỷ giá mua — tỷ giá mà khách hàng bán ngoại tệ
ask	decimal(18,4)	Tỷ giá bán — tỷ giá mà khách hàng mua ngoại tệ
quote_code	string(50)	Mã báo giá cho tỷ giá này. Dùng để đối chiếu và dành cho khóa tỷ giá
last_updated	string(19)	Thời gian tỷ giá được làm mới lần cuối. Định dạng: YYYY-MM-DD HH:MM:SS
valid_until	string(19)	Thời gian cho đến khi báo giá còn hiệu lực. Có thể null ở giai đoạn hiện tại

Ví dụ Response

{
  "response_code": 200,
  "response_message": "Thành công",
  "merchant_code": "MERCHANT1234",
  "data": [
    {
      "currency_pair": "USD/VND",
      "bid": 26450.0000,
      "ask": 26510.0000,
      "quote_code": "FXQ20260605101530USDVND0001",
      "last_updated": "2026-06-05 10:15:00",
      "valid_until": "2026-06-05 10:16:00"
    },
    {
      "currency_pair": "CNY/VND",
      "bid": 3600.5000,
      "ask": 3625.7000,
      "quote_code": "FXQ20260605101530CNYVND0002",
      "last_updated": "2026-06-05 10:15:00",
      "valid_until": "2026-06-05 10:16:00"
    }
  ]
}

Mã lỗi

Mã Response	Thông báo Response
200	Thành công
101	Lỗi hệ thống
110	Mã merchant không hợp lệ
120	Signature không hợp lệ
404	Cặp tiền tệ không được hỗ trợ
422	Lỗi xác thực
423	Tỷ giá FX không khả dụng
429	Quá nhiều yêu cầu