Giới thiệu API FX

Bộ API FX (ngoại hối) của Baokim cho phép Merchant lấy báo giá cam kết (firm quote), thực thi chuyển đổi ngoại hối, tra cứu trạng thái giao dịch, và tìm kiếm lịch sử tỷ giá theo khoảng thời gian.

1. Danh sách API

API	Endpoint	Method	Mục đích
Lấy báo giá FX	/api/v1/fx/quote	POST	Lấy báo giá cam kết (FIRM) hoặc tham khảo (INDICATIVE) cho nhu cầu chuyển đổi cụ thể
Thực thi chuyển đổi	/api/v1/fx/convert	POST	Thực thi chuyển đổi dựa trên quote_id từ Lấy báo giá FX
Tra cứu lệnh chuyển đổi	/api/v1/fx/conversion-detail	POST	Tra cứu trạng thái và chi tiết lệnh chuyển đổi
Lấy lịch sử tỷ giá	/api/v1/fx/historical-rate	POST	Tra cứu lịch sử tỷ giá theo ngày

2. Quy trình

Quy trình gồm 3 bước chính:

3. Các trường Request chung

Mỗi API request chứa các trường sau (ngoài trường cụ thể từng API):

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, unique theo Merchant. Định dạng gợi ý: MerchantCode + BK + YYYYMMDD + UniqueId. Riêng với Thực thi chuyển đổi, trường này đóng vai trò idempotency key.
request_time	string(19)	Có	Thời gian gửi request, múi giờ GMT+7. Định dạng: YYYY-MM-DD HH:MM:SS. Lệch quá ±5 phút → từ chối (mã 422).
merchant_code	string(20)	Có	Mã merchant được Baokim cung cấp trước khi tích hợp

4. Các trường Response chung

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
response_code	int(4)	Có	Mã kết quả, theo bảng Mã lỗi
response_message	string(200)	Có	Mô tả mã kết quả
merchant_code	string(20)	Có	Mã merchant
data	Object / Array	Có	Dữ liệu kết quả. Khi lỗi: null (Object) hoặc [] (Array)

Ví dụ response lỗi:

{
  "response_code": 110,
  "response_message": "Merchant code invalid",
  "merchant_code": "MERCHANT1234",
  "data": null
}

5. Quy ước tiền tệ và làm tròn

• Mã tiền tệ: ISO 4217, viết hoa (USD, CNY, VND…)
• VND: số nguyên, không chữ số thập phân
• Ngoại tệ: tối đa 2 chữ số thập phân (ví dụ USD 10.25)