FSTS API／FIX Message Mapping 明細

FSTS API／FIX Message Mapping 明細（呈核／設計協作版）

本文件將前台／外部系統以 REST API 溝通的介面，與後段上手以 FIX 溝通的訊息映射成同一張設計藍圖，避免 API 與 FIX 各做各的，導致欄位、狀態與錯誤碼不一致。¹

回到 介接規格書（總框架）、Planning 總覽。

1. Mapping 原則

²

• 外部通路以 OpenAPI 3.1 風格定義 REST 介面；交易核心事件以 FIX Session + Application Message 傳輸
• API 與 FIX 之間需有 canonical order／trade model，不可直接把上手欄位暴露到對客 API
• 所有關鍵鍵須可追：clientOrderId、brokerExecId、sessionId、traceId、messageSeqNo
• 拒單與例外需同時保有 API error code 與 FIX reject reason，便於客服與監控對位

2. REST API 介面清單

³⁴

Method	Path	功能	作用	前置條件	核心資料表	主要回應
POST	/api/v1/orders	下單	接收海外股票／ETF 委託	客戶已開通、商品可交易、額度檢核通過	ord_order、risk_trading_limit、acct_cash_balance	201 建單成功 ／ 422 檢核失敗
PUT	/api/v1/orders/{orderId}	改單	價格／數量修改	僅待送／部分成交未鎖定可改	ord_order、ord_order_event	200 修改成功
DELETE	/api/v1/orders/{orderId}	刪單	送出刪單請求	狀態允許且未全成交	ord_order、ord_order_event	202 已受理
GET	/api/v1/orders/{orderId}	委託查詢	查詢單筆委託含回報	需具該客戶資料權限	ord_order、trade_execution	200 查詢成功
GET	/api/v1/customers/{custId}/positions	庫存查詢	查詢商品庫存／可賣數	需具帳戶權限	acct_position	200 查詢成功
GET	/api/v1/customers/{custId}/balances	餘額查詢	查詢幣別餘額／圈存／可動用	需具帳戶權限	acct_cash_balance	200 查詢成功
POST	/api/v1/cash-withdrawals	出金申請	客戶申請出金	餘額足夠、帳戶有效、審核流程啟動	cash_movement、cust_bank_account	201 建立成功
POST	/api/v1/fx-deals	換匯申請	建立或確認換匯交易	已設定匯率來源與額度	fx_deal	201 建立成功
GET	/api/v1/corporate-actions	公司行動查詢	查詢公告與客戶選項	商品已建檔	ca_event、ca_allocation	200 查詢成功
POST	/api/v1/fix/sessions/{sessionId}/replay	FIX 重播	補送指定序號區間	操作權限與審核通過	fix_session、fix_message_log	202 已受理

3. FIX Message 對應清單

⁵⁶

FIX Message	MsgType	用途	對應 API／流程	核心檢核	落地結果
Logon	A	雙方建立 FIX Session	API Gateway／OMS 啟動連線	核對 SenderCompID / TargetCompID、EncryptMethod、HeartBtInt	認證成功後更新 fix_session
Heartbeat	0	維持連線活性	系統排程或被動回應	比對 TestReqID 與 session 狀態	記錄 fix_message_log
TestRequest	1	檢查對端存活	監控偵測延遲／人工觸發	在 SLA 內回 Heartbeat	監控告警
ResendRequest	2	補送序號區間	序號缺口或對帳補送	依 BeginSeqNo / EndSeqNo 重播	更新 message replay job
SequenceReset	4	重設序號	斷線重連或管理作業	GapFillFlag 檢核	更新 fix_session
Logout	5	正常關閉 Session	停機、切線、雙邊管理	保留最後序號與原因碼	關閉 fix_session
NewOrderSingle	D	新單委託	POST /orders	ClOrdID 唯一、Side、OrdType、Symbol、OrderQty、Price、TimeInForce、Account、Currency	建立 ord_order
OrderCancelReplaceRequest	G	改單	PUT /orders/{orderId}	OrigClOrdID、ClOrdID、價格／數量變更限制	更新 ord_order 狀態為 PendingReplace
OrderCancelRequest	F	刪單	DELETE /orders/{orderId}	OrigClOrdID、ClOrdID、Side、Symbol 一致	更新 ord_order 狀態為 PendingCancel
ExecutionReport	8	委託／成交回報	FIX → OMS／API	ExecType、OrdStatus、LastQty、LastPx、CumQty、LeavesQty、Text	更新 ord_order / trade_execution
Reject	3	Session 層拒絕	FIX → 監控／OMS	RefSeqNum、SessionRejectReason、Text	記錄 fix_message_log 與告警
BusinessMessageReject	j	業務層拒絕	FIX → OMS／API	RefMsgType、BusinessRejectReason、Text	更新 ord_order 為 Rejected

4. 關鍵欄位 Mapping 範例

⁷⁸

NewOrderSingle（D）→ POST /orders

FIX Tag	FIX 欄位	API／Canonical 欄位	說明	必填
11	ClOrdID	apiRequestId / clientOrderId	委託唯一鍵，平台生成且全域唯一	必填
55	Symbol	symbol	證券代碼，需對應商品主檔	必填
54	Side	side	1=Buy、2=Sell	必填
38	OrderQty	quantity	委託數量	必填
44	Price	price	限價單價格；市價單可為空	依單別
40	OrdType	orderType	1=Market、2=Limit	必填
59	TimeInForce	timeInForce	0=Day、6=GoodTillDate	依市場
1	Account	accountNo	客戶交易帳號	必填

ExecutionReport（8）→ Webhook／查詢回覆

FIX Tag	FIX 欄位	API／Canonical 欄位	說明	必填
150	ExecType	execType	0=New、4=Canceled、5=Replaced、F=Trade	必填
39	OrdStatus	orderStatus	0=New、1=PartiallyFilled、2=Filled、4=Canceled、8=Rejected	必填
17	ExecID	brokerExecId	上手成交／回報流水號	必填
32	LastQty	lastQty	本次成交量	成交時必填
31	LastPx	lastPx	本次成交價	成交時必填
14	CumQty	cumQty	累計成交量	必填
151	LeavesQty	leavesQty	剩餘未成交量	必填
58	Text	message	補充訊息或拒單原因	選填

5. 設計與驗收關鍵

⁹

• API 與 FIX 的 order status / exec type / reject reason 必須建立對照表，且測試案例需逐筆覆蓋
• FIX Session 層與業務層錯誤必須分開記錄，避免把 session reject 當成委託邏輯錯誤
• 所有回報需可由 traceId 串起 API request、FIX outbound、FIX inbound、order_event、trade_execution
• 當多家上手欄位差異存在時，應以 broker-specific adapter 處理，不污染核心 canonical model

6. 與 FIX 工作簿交付對齊

¹⁰

本頁以 16 號說明書 為主、17 號工作簿（REST_API_Catalog / FIX_Message_Catalog / FIX_Field_Mapping）為輔；兩者內容一致，工作簿提供可匯出成 Excel／可逐行驗收的形式，供 SIT／UAT 逐筆比對使用。

對應測試案例請見：FSTS 測試案例書（涵蓋 SIT / UAT / NFR / Migration 四類）。

相關頁面

• 介接總框架：介接規格書（FIX Gateway、API、SFTP、銀行、保管行、會計）
• 物理 Schema：實體資料表 DDL 草案（ord.*、ifx.*）
• 邏輯模型：邏輯資料模型（TRD_ORDER、INT_MESSAGE_LOG）
• 測試案例：測試案例書 §SIT / SIT-FIX
• 驗收矩陣：驗收矩陣 §C 非功能／§B 功能

補充資訊

2026-04-23 — 平行原版 raw（markdown 原稿）

CI sync 同一 commit (8b6bd5d) 帶入了相同內容的另一份原版 markdown（無數字前綴、無 PDF 轉檔殘留）。¹¹

• 本頁既有引用以 16 號前綴版（PDF 轉檔版）為主 anchor，此原版為平行佐證
• 兩份 Mapping 明細內容實質一致：§1 Mapping 原則、§2 REST API 介面清單（10 條）、§3 FIX Message 對應（12 條）、§4 關鍵欄位 Mapping、§5 設計與驗收關鍵皆對齊
• 原稿為條列式純文字表格，無 PDF 分頁殘留；查詢與審閱較順手
• 若需查閱乾淨 markdown 的 API／FIX Mapping 明細，請看：API／FIX Mapping 明細（原稿）

---

參考資料

Footnotes

1. 16 API FIX Mapping 明細 §文件標題 ↩

2. 16 API FIX Mapping §1 Mapping 原則 ↩

3. 16 API FIX Mapping §2 REST API 介面清單 ↩

4. 17 工作簿 §REST_API_Catalog ↩

5. 16 API FIX Mapping §3 FIX Message 對應清單 ↩

6. 17 工作簿 §FIX_Message_Catalog ↩

7. 16 API FIX Mapping §4 關鍵欄位 Mapping ↩

8. 17 工作簿 §FIX_Field_Mapping ↩

9. 16 API FIX Mapping §5 設計與驗收關鍵 ↩

10. 17 工作簿 §README ↩

11. API／FIX Mapping 明細（原稿）§1 Mapping 原則 ↩