群益API 刪單、改價、減量示意圖:依序號、書號或商品代號指定委託,回傳後以回報確認結果

群益API 刪單、改價、減量怎麼寫?七個函式與 Python 範例

刪單函式回傳 0,單子卻還在市場上。想把 3 口改成 1 口,減量填了 1,結果還剩 2 口。想加量,卻找不到對應的函式。刪單時該填序號還是書號,也分不清兩者的差別。

群益API 刪單、改價、減量可以先記四件事:回傳 0 只代表伺服器收到,結果要看回報;減量填的是「要減少幾口」;沒有加量的函式;依商品刪單時,商品代號留空會刪掉全部委託。

本文以官方元件說明文件 V2.13.59 為主。我們用 Python 實際操作過的只有一筆委託:SKCOM 2.13.57、證券盤中零股、收盤後送出,並對它刪單與改價各一次,下文會寫明條件。其餘的刪改單情境,在 Python 這一層我們沒有實測,只寫官方怎麼說。

群益API 刪單、改價、減量示意圖:依序號、書號或商品代號指定委託,回傳後以回報確認結果

群益API 刪改單有哪幾個函式?

官方手冊記載的國內刪改單函式有七個,差別在「用什麼找到那筆委託」:

動作函式用什麼指定委託
刪單CancelOrderBySeqNo13 碼委託序號
刪單CancelOrderByBookNo5 碼委託書號
刪單CancelOrderByStockNo商品代號
刪單CancelOrderByStockNoAdvance商品代號+買賣別(+委託價格)
改價CorrectPriceBySeqNo13 碼委託序號
改價CorrectPriceByBookNo5 碼委託書號+市場類別
減量DecreaseOrderBySeqNo13 碼委託序號

「13 碼」與「5 碼」的說法出自官方函式清單:CancelOrderBySeqNo 的說明寫「13 碼序號」,CancelOrderByBookNo 的說明寫「依5碼書號刪單」。下文把委託序號簡稱「序號」、委託書號簡稱「書號」。

市場的涵蓋範圍,官方寫法不一樣:

  • 改價:官方明寫涵蓋證券、期貨、選擇權。
  • 刪單、減量:參數說明列的是證券與期貨的帳號寫法,沒有另外提選擇權。

另外三點:

  • 沒有加量的函式。 官方函式清單只有「委託減量」,元件型別裡也找不到任何加量的函式。要多買,就是再下一筆新委託。
  • 元件裡另有一個手冊沒記載的 DecreaseOrderByBookNo,本文不教。
  • 智慧單的刪單是另一組函式,見〈群益API 智慧單回報去哪裡看〉。

群益API 委託序號和書號差在哪?從哪裡拿?

  • 13 碼委託序號:官方下單函式對 bstrMessage 的說明寫「同步委託:如果回傳值為 0表示委託成功,訊息內容則為13碼的委託序號。」非同步下單則從非同步結果事件 OnAsyncOrder 拿,見〈群益API 下單回傳值是 0 就成功了嗎〉。
  • 委託書號:在委託回報事件 OnNewData 的 OrderNo 欄,官方欄位說明是「委託書號」。一般委託的下單回傳裡有沒有書號,官方沒有說明。

所以,手上只有下單函式給的那串序號時,用 BySeqNo 系列最直接;要用書號,就從回報的 OrderNo 取。這是我們依上面兩個來源給的使用建議,不是官方規定。回報欄位的解析見〈群益API 委託回報怎麼解析〉。

群益API 刪單怎麼寫?回傳 0 代表刪掉了嗎?

七個函式的前三個參數都一樣(官方原文):

bstrLogInID   登入ID。
bAsyncOrder   是否為非同步委託。
bstrAccount   證券:委託帳號 (BrokerID+帳號)。
              期貨:委託帳號 ( IB+帳號) 。

刪單 CancelOrderBySeqNo 的宣告:

Long CancelOrderBySeqNo([in] BSTR bstrLogInID, [in] VARIANT_BOOL bAsyncOrder, [in] BSTR bstrAccount, [in] BSTR bstrSeqNo,[out] BSTR* bstrMessage);

回傳 0 不代表已經刪掉。 官方手冊的參數說明把回傳 0 寫成「成功」,同一節的備註再解釋這個「成功」的意思:

回傳值0 表示委託伺服器接收成功,詳細委託狀態仍須以委託刪單回報內容為主。

減量、改價的備註也是同一個意思,分別寫「委託減量回報」「委託改價回報」。所以回傳 0 之後,要等回報才知道刪掉了沒有,見下面「刪改單之後怎麼確認結果」。

回傳不是 0 的時候,以刪單 CancelOrderBySeqNo 的說明為例:

當錯誤代碼為4碼時,可參考6代碼定義表,所填欄位值說明請確認上方參數欄。

官方接著說明,其他錯誤由「交易主機」回傳錯誤代碼及錯誤原因。這兩種錯誤怎麼讀,見〈群益API 下單回傳 980 怎麼讀〉。這段說明只出現在部分刪改單函式裡,不是七個函式都這樣寫。

官方手冊的代碼定義表(錯誤碼對照表)裡,和序號、書號有關的兩個錯誤碼:

代碼常數官方說明
1090SK_ERROR_SEQNO_IS_INVALID委託序號有誤
1091SK_ERROR_BOOKNO_IS_INVALID委託書號有誤

我們在 2.13.57 用 Python 實際操作過一次刪單:證券盤中零股、收盤後送出的 1 股委託,同步呼叫 CancelOrderBySeqNo 回 0,之後回報收到 Type=C、OrderErr=N。

群益API 改價怎麼寫?價格、時效碼與盤中零股

Long CorrectPriceBySeqNo([in] BSTR bstrLogInID, [in] VARIANT_BOOL bAsyncOrder, [in] BSTR bstrAccount, [in] BSTR bstrSeqNo, [in] BSTR bstrPrice, [in] LONG nTradeType,[out] BSTR* bstrMessage);
Long CorrectPriceByBookNo([in] BSTR bstrLogInID, [in] VARIANT_BOOL bAsyncOrder, [in] BSTR bstrAccount, [in] BSTR bstrMarketSymbol, [in] BSTR bstrBookNo, [in] BSTR bstrPrice, [in] LONG nTradeType,[out] BSTR* bstrMessage);

價格是字串。 bstrPrice 官方說明「修改價格。」,型態是 BSTR,跟下單一樣,見〈群益API 下單價格為什麼是字串〉。

時效碼要填。 時效碼是委託的有效條件,參數是 nTradeType:ROD 是當日有效,IOC 是立即成交、未成交部分取消,FOK 是全部成交、否則全部取消。官方的說明:

證券0:ROD 期選0:ROD 1:IOC 2:FOK

證券只有 0(ROD);期貨與選擇權是 0 ROD、1 IOC、2 FOK。智慧單的時效碼又是另一套(0 ROD、3 IOC、4 FOK),三套不能混用,見〈群益API 觸價單(MIT)一直被退〉。

盤中零股不能改價。 官方備註:

*證券逐筆nTradeType:請設0(ROD). *不適用盤中零股

我們在 2.13.57 用 Python 對前面那筆證券盤中零股、收盤後送出的委託呼叫 CorrectPriceBySeqNo,被退回,訊息是「輸入欄位有誤, 此市場/盤別不可改價 !」,與官方的「不適用盤中零股」一致。零股要改價,只能刪單後重下。

依書號改價要多填市場類別。 CorrectPriceByBookNo 的 bstrMarketSymbol,官方說明是「市場類別 TS: 證券TF:期貨 TO:選擇權」。這裡填的是市場類別,不是商品代號。CancelOrderByBookNo 沒有這個參數。

群益API 減量填的是什麼?3 口改 1 口要填 2

Long DecreaseOrderBySeqNo([in] BSTR bstrLogInID, [in] VARIANT_BOOL bAsyncOrder, [in] BSTR bstrAccount, [in] BSTR bstrSeqNo, [in] LONG nDecreaseQty,[out] BSTR* bstrMessage);

官方對 nDecreaseQty 的說明:

欲減少的數量。

填的是要減少的數量,不是改完剩多少。 以期貨的口數為例,依這個定義,3 口要改成 1 口,nDecreaseQty 填 2;填 1 會剩 2 口。

回報這邊也一致:官方 OnNewData 欄位表裡,Type 為 U(改量)時,Qty 是這次減掉的數量,不是剩下幾口。拿它直接覆蓋本地記錄的委託量,就會算錯,見〈群益API 委託回報怎麼解析〉。

群益API 依商品刪單:商品代號留空會刪掉全部委託

Long CancelOrderByStockNo([in] BSTR bstrLogInID, [in] VARIANT_BOOL bAsyncOrder, [in] BSTR bstrAccount, [in] BSTR bstrStockNo,[out] BSTR* bstrMessage);

官方對 bstrStockNo 的說明:

欲刪除的委託商品代號。(帶空字串,可刪除帳號下所有委託)

版本控管表 2024/12/19 的 2.13.52 也寫:

修改國內委託刪改單CancelOrderByStockNo (不輸入商品代碼即刪除全部委託)

商品代號帶空字串,會刪除全部委託,官方的參數說明與版本控管表都這樣寫。但「全部」的範圍,官方寫法不一樣:參數說明寫的是「帳號下所有委託」,同一節的標題與函式清單則寫:

國內委託删單(By帳號所屬登入ID+商品代號)。

範圍是這一個帳號,還是這個登入 ID 底下的所有帳號,官方沒有講清楚,我們也沒有實測。

程式裡如果商品代號來自設定檔或使用者輸入,呼叫前要先檢查它不是空字串。官方備註另外提醒:「*請留意證券代碼,包含刪除盤中零股委託」。

只想刪某一邊或某個價位,可以用 2.13.52 新增的 CancelOrderByStockNoAdvance:

Long CancelOrderByStockNoAdvance([in] BSTR bstrLogInID, [in] VARIANT_BOOL bAsyncOrder, [in] BSTR bstrAccount, [in] BSTR bstrStockNo, [in] LONG nBuySell, [in] BSTR bstrPrice, [out] BSTR* bstrMessage);

官方說明:bstrStockNo「欲刪除的委託商品代號,請輸入有效商品代碼。」、nBuySell「0:買進 1:賣出」、bstrPrice「委託價格(不使用請帶空字串)」。這個函式的商品代號要有效,與 CancelOrderByStockNo 不同。這兩個函式我們都沒有實測。

群益API 刪改單之後怎麼確認結果?

回傳 0 之後,要看委託回報 OnNewData。官方欄位說明:

Type N:委託 C:取消 U:改量 P:改價D:成交 B:改價改量S:動態退單

OrderErr Y:失敗 T:逾時 N:正常

依這兩個欄位的定義,各動作要等的回報:

動作要等的回報
刪單Type=C、OrderErr=N
改價Type=P 或 B、OrderErr=N
減量Type=U、OrderErr=N

我們實際看過的只有刪單的 Type=C:2.13.57、Python、證券盤中零股收盤後送出的那一筆。改價與減量的回報,我們沒有實測。

兩條處理原則:

  1. 失敗回報不要改本地的委託狀態。 OrderErr 不是 N 時,委託還在市場上。如果刪單失敗卻在本地把那筆移除,畫面上就看不到一筆其實還在的委託,也沒辦法再刪它。對帳的做法見〈群益API 委託回報怎麼對帳〉。
  2. 程式有模擬模式時,模擬的刪改單不要回「成功」。 刪改的對象是真實委託,回假成功會讓人以為已經刪掉,實際上委託還在市場上。

刪改單前也要先確認回報通道已經就緒,否則送出去也看不到結果,見〈群益API 下單初始化有哪 7 步〉。

群益API 刪單 Python 範例:拆包成訊息與回傳碼

七個函式的參數都是 [in],只有最後的 bstrMessage 是 [out],沒有 [in,out]。Python 呼叫時不要傳 bstrMessage,它會跟回傳碼一起回來,順序是訊息在前、回傳碼在後:

message, code = order.CancelOrderBySeqNo("YOUR_ID", False, "YOUR_ACCOUNT", seq_no)

順序的依據有三個:元件型別裡 bstrMessage 排在回傳碼前面;我們在 2.13.57 實際操作時用的拆分程式,取第一個當訊息、最後一個當回傳碼;同一批實際操作中,下單成功時第一個元素是 13 位數字的委託序號、第二個是 0。回傳的是 list 還是 tuple 不影響,直接拆包就好,見〈群益API Python 回傳值為什麼是 list〉。

bAsyncOrder 傳 False 是同步,呼叫回傳時就拿到訊息與回傳碼;傳 True 是非同步,回傳 0 只表示請求已送出,刪改的結果由 OnAsyncOrder 事件通知。

下面的範例把三個常用動作包成函式。前提是已經完成登入與下單元件初始化,見〈群益API Python 入門〉。

LOGIN_ID = "YOUR_ID"
ACCOUNT = "YOUR_ACCOUNT"     # 期貨:IB+帳號;證券:BrokerID+帳號
SIMULATION = True            # 模擬開關:True 時只印出參數,不呼叫任何函式

def call(name, *args):
    """呼叫刪改單函式;回傳 (訊息, 回傳碼),順序與直接呼叫相同。真正結果要看回報"""
    if SIMULATION:                          # 刪改的對象是真實委託,模擬時不要回假成功
        print("模擬,未送出:", name, args)
        return "模擬模式,未送出", -1
    message, code = getattr(order, name)(LOGIN_ID, False, ACCOUNT, *args)
    return message, int(code)

def cancel(seq_no):                         # 13 碼委託序號
    return call("CancelOrderBySeqNo", seq_no)

def correct_price(seq_no, price, trade_type=0):   # 價格傳字串;0:ROD 1:IOC 2:FOK(期選)
    return call("CorrectPriceBySeqNo", seq_no, str(price), trade_type)

def decrease(seq_no, qty):                  # qty 是「要減少的數量」,不是改後剩幾口
    return call("DecreaseOrderBySeqNo", seq_no, qty)

這段範例我們只在模擬模式下跑過:三個包裝函式都只印出參數、回傳 ("模擬模式,未送出", -1),沒有呼叫任何刪改單函式。

三點補充:

  • getattr(order, name) 是為了讓三個動作共用同一段程式;直接呼叫也可以,參數順序照上面的宣告。
  • 價格統一用 str(price) 轉成字串再傳。
  • 確認結果要看回報,範例沒有放這一段,整合的寫法見〈群益API Python 程式架構〉。

群益API 刪改單的 4 個誤解

  1. 誤解: 刪單回傳 0 就刪掉了。其實: 官方備註說明回傳 0 表示委託伺服器接收成功,狀態以刪單回報為準,要等 Type=C、OrderErr=N。
  2. 誤解: nDecreaseQty 填改完剩幾口。其實: 官方說明是「欲減少的數量」,3 口改 1 口要填 2。
  3. 誤解: 有減量,就有加量。其實: 官方只有減量函式,元件裡沒有加量的函式;要多買就另下一筆。
  4. 誤解: 序號和書號是同一個東西。其實: 序號是 13 碼,同步下單成功時就在 bstrMessage;書號在回報的 OrderNo 欄。兩組函式各用各的。

常見問題

群益API 刪單回傳 0,為什麼單子還在?

回傳 0 只代表委託伺服器收到了刪單要求。官方備註寫明,詳細狀態要以刪單回報為準:收到 Type=C、OrderErr=N 才算刪掉。

群益API 減量要怎麼填?

nDecreaseQty 填要減少的數量。3 口要改成 1 口,填 2。

群益API 可以加量嗎?

官方只有減量函式,元件裡也找不到加量的函式。要多買,就另外下一筆新委託。

刪單用序號還是書號比較好?

手上只有下單函式回來的那串 13 碼序號時,用 CancelOrderBySeqNo 最直接;書號要從委託回報的 OrderNo 欄取。這是我們的使用建議,兩組函式官方都有提供。

風險揭露

期貨與選擇權屬高槓桿商品,價格波動可能造成超過原始保證金的損失,交易人須自負交易責任。本文為程式開發技術教學,說明 Python 呼叫群益API 刪單、改價、減量函式的方式,不構成投資建議,也不保證任何交易結果。程式化交易並不降低市場風險,刪改單結果判讀錯誤可能讓程式誤判委託狀態,正式使用前請充分測試。

投資人教育資源

機構資源
臺灣期貨交易所(TAIFEX)期貨及選擇權數位學習網
證券暨期貨市場發展基金會證券期貨市場教育推廣
金融智慧網金管會金融知識平台
中華民國期貨業商業同業公會期貨業法規與宣導
證券投資人及期貨交易人保護中心投資人保護與申訴

延伸閱讀

參考資料

  • CancelOrderBySeqNo、CancelOrderByBookNo、CancelOrderByStockNo、CancelOrderByStockNoAdvance、CorrectPriceBySeqNo、CorrectPriceByBookNo、DecreaseOrderBySeqNo 的宣告與說明、OnNewData 欄位、版本控管表 2.13.52、錯誤碼 1090 與 1091,依群益官方元件說明文件 V2.13.59。
  • 參數方向、沒有加量函式:依 SKCOM 2.13.59 x64 的元件型別,我們 2026-11-07 以 comtypes 1.4.16 核對。
  • 刪單回 0 與回報 Type=C、改價被退的訊息:我們 2026-09-09 在 SKCOM 2.13.57、Python、正式環境,對一筆證券盤中零股、收盤後送出的委託實際操作的結果,非官方文件記載。其他刪改單情境在 Python 這一層我們沒有實測。

免責聲明

本文章僅作為群益API實作經驗分享,不構成投資建議,且策略及程式皆應自行撰寫。期貨及衍生性金融商品交易屬高風險投資,請謹慎評估自身風險承擔能力。

延伸閱讀|相關文章

發佈留言

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