群益API 期貨下單怎麼寫?FUTUREORDER 欄位逐一填與 Python 範例
在 Python 裡建立 FUTUREORDER 結構,會看到一大堆欄位,不知道哪些要填。期貨要用 SendFutureOrder 還是 SendFutureOrderCLR,選擇權又是哪一個函式,也分不清楚。夜盤下單的盤別該填 0 還是 1,同樣讓人猶豫。
群益API 期貨下單可以先記四件事:期貨用 SendFutureOrderCLR,選擇權用 SendOptionOrder;只填官方「一般期選委託」小節列的欄位;每個欄位都明確填,不靠預設值;夜盤的盤別 sReserved 同樣填 0。
本文以官方元件說明文件 V2.13.59 為主。期貨下單我們用 Python 實際送過一筆:SKCOM 2.13.57、夜盤時段,被交易主機以帳戶條件退回。這只能說明這組欄位送得出去、主機有回覆,不代表我們用 Python 下期貨成功過。 選擇權下單我們沒有用 Python 實際送過,相關內容只寫官方怎麼說。

目錄
群益API 期貨、選擇權下單用哪個函式?
| 函式 | 官方說明 |
|---|---|
SendFutureOrder | 「(新客戶請使用4-2-8)」「送出期貨委託,不需填倉位,盤別預設為盤中,不可更改。」 |
SendFutureOrderCLR | 「送出期貨委託,需設倉別與盤別。」 |
SendOptionOrder | 「送出選擇權委託,需設盤別。」 |
期貨用 SendFutureOrderCLR,選擇權用 SendOptionOrder。 SendFutureOrder 在官方手冊的章節編號是 4-2-7,官方標示新客戶請改用 4-2-8(SendFutureOrderCLR);V2.13.59 手冊的 4-2-7 只剩上面兩句說明,沒有宣告。
SendFutureOrderCLR 與 SendOptionOrder 的宣告:
Long SendFutureOrderCLR([in] BSTR bstrLogInID, [in] VARIANT_BOOL bAsyncOrder, [in] struct FUTUREORDER* pAsyncOrder,[out] BSTR* bstrMessage);
Long SendOptionOrder([in] BSTR bstrLogInID, [in] VARIANT_BOOL bAsyncOrder, [in] struct FUTUREORDER* pOrder,[out] BSTR* bstrMessage);兩個函式都吃同一個結構 FUTUREORDER,而且沒有帳號參數,帳號填在結構的 bstrFullAccount 裡。這跟刪單、改價的函式不一樣:刪改單是把帳號當參數傳,見〈群益API 刪單、改價、減量怎麼寫〉。
群益API FUTUREORDER 有 36 個欄位,要填哪些?
在 Python 裡,sk.FUTUREORDER() 建出來的結構有 36 個欄位。官方手冊沒有一次列出這 36 個,而是在 FUTUREORDER(期權下單物件) 底下分成好幾個小節,各小節只列出各自要用的欄位。同一個欄位在不同小節,代碼值可能不一樣:
| 小節 | 用在哪 | 和一般委託的差別 |
|---|---|---|
| 一般期選委託 | SendFutureOrderCLR、SendOptionOrder | 本文介紹的就是這一節 |
| 全拆組單 | 全拆組、全拆組平委託 | 只有帳號與 nFunType 兩個欄位 |
| 期、選智慧單 | 智慧單 | sTradeType 是「0:ROD 3:IOC 4:FOK」,見〈群益API 觸價單(MIT)一直被退〉 |
| 選擇權複式單 | 複式單 | 另有專用函式,本文不談 |
上表只列出幾個常見的小節,手冊裡還有其他小節。
一般委託只需要填「一般期選委託」小節列出的 12 個欄位,其他欄位不用碰。
群益API 一般期選委託的 12 個欄位怎麼填?
官方「一般期選委託」小節的結構(欄位名與型別之間的空格是我們補的,註解一字未改):
struct FUTUREORDER
{
BSTR bstrFullAccount; //期貨帳號,Broker id (例如: F020000)+帳號7碼
BSTR bstrStockNo; //委託期權代號
SHORT sTradeType; //0:ROD 1:IOC 2:FOK
SHORT sBuySell; //0:買進 1:賣出
SHORT sDayTrade; //當沖0:否 1:是,可當沖商品請參考交易所規定。
SHORT sNewClose; //新平倉,0:新倉 1:平倉 2:自動{新期貨、選擇權使用}
BSTR bstrPrice; //委託價格(IOC and FOK,可用「M」表示市價,「P」表示範圍市價)
LONG nQty; //交易口數
SHORT sReserved; //{期貨委託SendFutureOrderCLR適用}盤別,0:盤中(T盤及T+1盤);1:T盤預約
BSTR bstrCIDTandem; //委託期權代號2(例如FITX、FIMTX)
BSTR bstrSettlementMonth; //第一腳年月(yyyymm)
BSTR bstrSettlementMonth2; //第二腳年月(yyyymm)
};逐欄說明:
| 欄位 | 型別 | 怎麼填 |
|---|---|---|
bstrFullAccount | 字串 | Broker ID 加帳號 7 碼;帳號的取法見〈群益API 下單初始化有哪 7 步〉 |
bstrStockNo | 字串 | 商品代碼(不是交易所代碼),見〈群益API 商品代碼怎麼填〉 |
sTradeType | 整數 | 0 ROD、1 IOC、2 FOK;智慧單是另一套 |
sBuySell | 整數 | 0 買進、1 賣出 |
sDayTrade | 整數 | 0 否、1 是;官方註明「可當沖商品請參考交易所規定」 |
sNewClose | 整數 | 0 新倉、1 平倉、2 自動 |
bstrPrice | 字串 | 價格是字串,見〈群益API 下單價格為什麼是字串〉 |
nQty | 整數 | 交易口數 |
sReserved | 整數 | 0 盤中(T 盤及 T+1 盤)、1 T 盤預約,見下文 |
bstrCIDTandem | 字串 | 商品指定的第二種方法用,見下文 |
bstrSettlementMonth | 字串 | 第一腳年月,6 碼 |
bstrSettlementMonth2 | 字串 | 第二腳年月,6 碼 |
兩個欄位的官方註解,原文就是這樣,官方沒有進一步說明:
sNewClose註解最後的「{新期貨、選擇權使用}」。sNewClose的「2:自動」是什麼意思。
bstrSettlementMonth2 在這個小節只寫「第二腳年月(yyyymm)」,沒有說明什麼時候要用。
群益API 期貨下單的商品怎麼指定?兩種方法
官方 4-2-8 的備註:
V2.13.54(含) 新增下單欄位bstrCIDTandem、bstrSettlementMonth。 目前下單商品規格有兩種方法: 1. bstrStockNo帶入TX03。 注意:委託TX03如果今年TX03已過期,則會自動委託隔年TX03。 2. bstrCIDTandem帶入FITX,bstrSettlementMonth帶入202503。
- 方法 1:
bstrStockNo填具體月份的商品代碼,例如TX03。代碼怎麼查,見〈群益API 商品代碼怎麼填〉。 - 方法 2:
bstrCIDTandem填商品名稱、bstrSettlementMonth填年月,元件要 2.13.54 以上。這個方法我們沒有實測。
注意官方那句「今年已過期,則會自動委託隔年」。 商品代碼若寫死在程式裡,月份過期後送出的就會是隔年的合約,所以代碼要每次從商品清單取。
兩種方法的欄位同時填的話,哪一個優先,官方沒有說明。本文的範例只用方法 1,bstrCIDTandem 與 bstrSettlementMonth 不填。
群益API 夜盤下單的 sReserved 要填 0 還是 1?
填 0。 官方註解:「0:盤中(T盤及T+1盤);1:T盤預約」。T+1 盤(夜盤)包含在 0 裡面,1 是 T 盤的預約,不是夜盤。
我們在 2.13.57 用 Python、在夜盤時段,以 sReserved = 0 送出一筆台指期 1 口的 ROD 限價委託,交易主機有回覆:回傳 980,委託回報 Type=N、OrderErr=Y,原因是帳戶條件,不是盤別。這只能說明夜盤填 0 送得出去、主機有回覆,不能說明會成交。980 的讀法見〈群益API 下單回傳 980 怎麼讀〉。sReserved = 1 我們沒有實測。
選擇權的盤別,官方兩處寫法對不上:
- 4-2-9
SendOptionOrder的說明寫「送出選擇權委託,需設盤別。」 sReserved的註解寫「{期貨委託SendFutureOrderCLR適用}盤別」。
哪一句才對,官方沒有說明。我們的建議是選擇權也填 0:0 在兩種讀法下都不會選到預約。這是我們的使用建議,不是官方規定,而且選擇權下單我們沒有 Python 實機。
群益API FUTUREORDER 漏填欄位會怎樣?
建立結構時,不會因為沒填欄位而報錯。 我們在本機實際建立結構(只建立、沒有送單),新建結構的字串欄位是 None,數值欄位是 0。
而依官方的代碼定義,0 在這幾個欄位都對應到一個有效的值:
| 欄位 | 0 代表 |
|---|---|
sTradeType | ROD |
sBuySell | 買進 |
sDayTrade | 否(非當沖) |
sNewClose | 新倉 |
sReserved | 盤中 |
漏填的欄位送出後,元件或交易主機會不會擋下來,我們沒有實測。結構本身不會提醒你漏填,所以每個欄位都要明確填,不要靠預設值。
群益API 下單回傳的 13 碼是什麼?
官方對 bstrMessage 的說明:
同步委託:如果回傳值為 0表示委託成功,訊息內容則為13碼的委託序號。
回傳非 0 時,官方說明這表示委託異常,並請確認委託回報,訊息內容是失敗原因。非同步委託則參照 OnAsyncOrder。
同一節的備註最後一行:
*此處委託成功,是指成功送至交易所,交易所回覆結果請由回報確認
所以回傳 0 不等於成交,結果要看委託回報,見〈群益API 下單回傳值是 0 就成功了嗎〉。
- 13 碼是委託序號,不是書號。 這串序號可以接
BySeqNo系列的刪單、改價、減量函式,見〈群益API 刪單、改價、減量怎麼寫〉。依據是官方文字;期貨下單成功、拿到序號這條路徑,我們沒有實測。 - 回傳非 0 時,下單函式的說明寫:「當錯誤代碼為4碼時,可參考6代碼定義表,所屬委託物件亦有欄位值說明供參。」其他錯誤由交易主機回傳,見〈群益API 下單回傳 980 怎麼讀〉。
群益API 期貨下單 Python 範例:建立結構、逐欄填、送出
前提是已經完成登入與下單元件初始化,見〈群益API Python 入門〉。送單前也要先設好下單上限、確認回報通道已經就緒,見〈群益API 下單初始化有哪 7 步〉。
LOGIN_ID = "YOUR_ID"
ACCOUNT = "YOUR_ACCOUNT" # 期貨帳號:Broker ID+帳號 7 碼
SIMULATION = True # 模擬開關:True 時只印出欄位,不呼叫下單函式
def build_order(stock_no, buy_sell, price, qty, trade_type=0,
day_trade=0, new_close=0, reserved=0):
"""依官方「一般期選委託」小節填 FUTUREORDER;每個欄位都明確填,不靠預設值"""
o = sk.FUTUREORDER()
o.bstrFullAccount = ACCOUNT
o.bstrStockNo = stock_no # 具體月份的商品代碼,從商品清單取
o.sTradeType = trade_type # 0:ROD 1:IOC 2:FOK
o.sBuySell = buy_sell # 0:買進 1:賣出
o.sDayTrade = day_trade # 當沖 0:否 1:是
o.sNewClose = new_close # 0:新倉 1:平倉 2:自動
o.bstrPrice = str(price) # 價格是字串
o.nQty = qty # 交易口數
o.sReserved = reserved # 盤別 0:盤中(T盤及T+1盤) 1:T盤預約
return o
def send(func_name, o):
"""func_name:期貨用 SendFutureOrderCLR,選擇權用 SendOptionOrder。回傳 (訊息, 回傳碼)"""
if SIMULATION: # 模擬時不要回假成功
fields = ("bstrStockNo", "sTradeType", "sBuySell", "sDayTrade",
"sNewClose", "bstrPrice", "nQty", "sReserved")
print("模擬,未送出:", func_name, {f: getattr(o, f) for f in fields})
return "模擬模式,未送出", -1
message, code = getattr(order, func_name)(LOGIN_ID, False, o)
return message, int(code) # 同步成功時 message 是 13 碼委託序號;結果仍以回報為準使用方式:
message, code = send("SendFutureOrderCLR", build_order("TX03", 0, 20000, 1))"TX03" 取自官方 4-2-8 備註的範例,20000 只是示意用的價格。代碼與價格請換成你從商品清單與報價拿到的值。
這段範例我們只在模擬模式下跑過:build_order 填出的欄位正確,send 只印出欄位、回傳 ("模擬模式,未送出", -1),沒有呼叫任何下單函式。
三點補充:
- 回傳拆包成
message, code,順序與刪改單函式相同,見〈群益API Python 回傳值為什麼是 list〉。 - 價格統一用
str(price)轉成字串再傳。 - 範例沒有示範方法 2、價差單與市價。
群益API 價差單怎麼填?官方備註原文
官方「一般期選委託」小節的備註:
如果要下價差單,bstrStockNo請帶入:”近月/遠月”, sBuySell買賣別為近月 範例:買TX12/01,bstrStockNo = “TX12/01”、 sBuySell = 1 (賣出)
官方寫明 sBuySell 是近月的買賣別,並舉「買 TX12/01」對應 sBuySell = 1(賣出)。價差單我們沒有實測,本文只列官方原文,範例也不包含價差單。
群益API 期貨下單的 4 個誤解
- 誤解: 期貨下單用
SendFutureOrder。其實: 官方標示新客戶請使用 4-2-8SendFutureOrderCLR。 - 誤解: 夜盤要把
sReserved填 1。其實: 0 就是「盤中(T盤及T+1盤)」,1 是 T 盤預約。 - 誤解: 沒填的欄位會報錯。其實: 建立結構時不會因為沒填欄位而報錯,數值欄位預設是 0,而 0 在
sBuySell、sNewClose等欄位分別代表買進、新倉,所以每個欄位都要明確填。 - 誤解: 同步回傳的那串數字是書號。其實: 官方寫的是 13 碼的委託序號;書號在委託回報的
OrderNo欄。
常見問題
群益API 期貨下單用 SendFutureOrder 還是 SendFutureOrderCLR?
用 SendFutureOrderCLR。官方在 SendFutureOrder 標示「新客戶請使用4-2-8」,也就是 SendFutureOrderCLR。選擇權則用 SendOptionOrder。
夜盤下單 sReserved 要填多少?
填 0。官方註解是「0:盤中(T盤及T+1盤);1:T盤預約」,夜盤(T+1 盤)包含在 0 裡面。
下單回傳的 13 碼數字是書號嗎?
不是。官方寫的是「13碼的委託序號」,可以拿來給 BySeqNo 系列的刪單、改價、減量函式用。書號在委託回報的 OrderNo 欄。
FUTUREORDER 的 36 個欄位都要填嗎?
不用。在 Python 裡 sk.FUTUREORDER() 有 36 個欄位,官方手冊則是分小節列出各自要用的欄位。一般委託只填「一般期選委託」小節列的 12 個欄位。
風險揭露
期貨與選擇權屬高槓桿商品,價格波動可能造成超過原始保證金的損失,交易人須自負交易責任。本文為程式開發技術教學,說明 Python 呼叫群益API 期貨、選擇權下單函式的欄位填法,不構成投資建議,也不保證任何交易結果。程式化交易並不降低市場風險,欄位填錯可能讓委託的方向、倉別或商品與預期不同,正式使用前請充分測試。
投資人教育資源
| 機構 | 資源 |
|---|---|
| 臺灣期貨交易所(TAIFEX) | 期貨及選擇權數位學習網 |
| 證券暨期貨市場發展基金會 | 證券期貨市場教育推廣 |
| 金融智慧網 | 金管會金融知識平台 |
| 中華民國期貨業商業同業公會 | 期貨業法規與宣導 |
| 證券投資人及期貨交易人保護中心 | 投資人保護與申訴 |
延伸閱讀
- 〈群益API 商品代碼怎麼填〉——TX09、TX00 與交易所代碼的差別。
- 〈群益API 下單價格為什麼是字串〉——送出前要自己檢查的事。
- 〈群益API 刪單、改價、減量怎麼寫〉——拿到 13 碼序號之後。
- 〈群益API 下單回傳 980 怎麼讀〉——錯誤碼與交易主機的退單訊息。
參考資料
SendFutureOrder、SendFutureOrderCLR、SendOptionOrder的說明與宣告、FUTUREORDER「一般期選委託」小節與各小節的欄位、版本控管表 2.13.54,依群益官方元件說明文件 V2.13.59。FUTUREORDER的 36 個欄位與新建結構的預設值:依 SKCOM 2.13.59 x64 的元件型別,我們 2026-11-07 以 comtypes 1.4.16 核對。- 夜盤以
sReserved = 0送出、交易主機以帳戶條件退單:我們 2026-09-09 在 SKCOM 2.13.57、Python、正式環境的實際操作結果,非官方文件記載。期貨下單成功、選擇權下單等其他情境,在 Python 這一層我們沒有實測。
免責聲明
本文章僅作為群益API實作經驗分享,不構成投資建議,且策略及程式皆應自行撰寫。期貨及衍生性金融商品交易屬高風險投資,請謹慎評估自身風險承擔能力。







