群益API 期貨下單示意圖:FUTUREORDER 結構逐欄填好,交給 SendFutureOrderCLR 送出

群益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 期貨下單示意圖:FUTUREORDER 結構逐欄填好,交給 SendFutureOrderCLR 送出

群益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 代表
sTradeTypeROD
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 個誤解

  1. 誤解: 期貨下單用 SendFutureOrder。其實: 官方標示新客戶請使用 4-2-8 SendFutureOrderCLR。
  2. 誤解: 夜盤要把 sReserved 填 1。其實: 0 就是「盤中(T盤及T+1盤)」,1 是 T 盤預約。
  3. 誤解: 沒填的欄位會報錯。其實: 建立結構時不會因為沒填欄位而報錯,數值欄位預設是 0,而 0 在 sBuySell、sNewClose 等欄位分別代表買進、新倉,所以每個欄位都要明確填。
  4. 誤解: 同步回傳的那串數字是書號。其實: 官方寫的是 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)期貨及選擇權數位學習網
證券暨期貨市場發展基金會證券期貨市場教育推廣
金融智慧網金管會金融知識平台
中華民國期貨業商業同業公會期貨業法規與宣導
證券投資人及期貨交易人保護中心投資人保護與申訴

延伸閱讀

參考資料

  • 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實作經驗分享,不構成投資建議,且策略及程式皆應自行撰寫。期貨及衍生性金融商品交易屬高風險投資,請謹慎評估自身風險承擔能力。

延伸閱讀|相關文章

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *