群益API 下單初始化有哪 7 步？少一步就會在別的地方報錯

群益API 下單初始化沒做完的時候，錯誤碼未必會指向你漏掉的那一步。下單函式回 1000（請先登入），但你明明登入成功了。或者回 1038（憑證尚未驗章），於是你開始查憑證。

這條鏈最難處理的性質就在這裡：錯誤出現的位置，和根因的位置不是同一個。 你拿到的碼指向憑證，真正沒做完的可能是更前面的某一步。

群益API 下單初始化有哪 7 步？

群益API 下單初始化的完整順序如下——注意第一步在登入之前：

1. 建立 SKReplyLib 物件並註冊 OnReplyMessage
2. 登入
3. SKOrderLib_Initialize
4. ReadCertByID
5. GetUserAccount
6. SKReplyLib_ConnectByID
7. 等 OnComplete，才開放送單

中間三步的官方備註值得一起看：

三句都是「先……才……」的句型——官方自己就是用順序在描述它們。

群益API 下單初始化不是幾個可以各自打開的開關，是一條鏈。 而每一步沒做的後果，會在後面某個看起來無關的地方冒出來。

取不到帳號的時候

GetUserAccount 拿不到帳號、或拿到的帳號不能用時，不一定是程式的問題——這一步可能卡在帳戶側的狀態，那不是改程式能解決的。先確認前面幾步的回傳值都是 0，如果都正常而帳號還是取不到，就不要再往程式裡找了。

如果有遇到這類的問題可以先跟您的營業員反應。

第一步其實在登入之前

群益API 下單初始化有一步很多人不會預期：登入之前必須先建立 SKReplyLib 物件、註冊 OnReplyMessage，並在處理常式裡把 sConfirmCode 設為 -1。

沒做這一步，SKCenterLib_Login 不會回 0，而是回 2017。

所以「回報」這件事不是下單之後才要處理的，它在你登入之前就已經開始了。 這個定位在〈群益API 是什麼〉與〈群益API 登入錯誤怎麼判讀〉都寫過，這裡只放在鏈上，不重述細節。

回報通道「連上」不等於「可以用」

這是群益API 下單初始化最後一步，也是「下單送出去了、回報卻對不起來」的成因。

SKReplyLib_ConnectByID 有兩個通知事件：OnSolaceReplyConnection 與 OnComplete。官方對 OnComplete 的說明是：

回報連線後會進行回報回補，等收到此事件通知後表示回補完成

也就是說——連線建立之後，系統會先把先前的回報補送給你。OnComplete 到了，才代表回補結束，之後收到的才是新的回報。

如果在回補完成之前就送單，你的回報處理會同時面對兩批東西：歷史回補、以及新委託的回報。而它們走同一個事件。

程式剛啟動的前幾秒下單、回報卻對不起來，先檢查是不是撞到這一段。

這個模式你已經見過一次

如果你讀過報價那幾篇會覺得眼熟：深度層訂閱會附帶當天的 Tick 回補，訂閱的當下先收到一批歷史資料，那些不是即時成交。

這裡是同一個模式，只是換了資料種類——報價那邊是 Tick，回報這邊是委託回報。

連上線就先給你一批舊資料，是這套 API 反覆出現的設計。 認得這個模式之後，下次在別的地方遇到「一連上就湧進一堆東西」，你會先想到它。

另外補一個實作上的觀察：SKReplyLib_ConnectByID 回 0 只代表連線請求送出去了，不代表通道就緒——要等事件才算數。（這一點是實作歸納，官方文件沒有明文，但它與上面那句官方說明的方向一致。）

群益API 下單初始化之後：用一個旗標控制送單開放

把初始化寫成一條有順序、每一步都檢查回傳值的流程，而不是散在各處的初始化程式碼。最後一步交給事件：

// 初始化是一條鏈：每一步都要確認，不要一路往下送
int nCode = m_pSKOrder.SKOrderLib_Initialize();
if (nCode != 0) { ShowError(nCode); return; }

nCode = m_pSKOrder.ReadCertByID(userId);        // 沒做這步，之後下單會回 1038
if (nCode != 0) { ShowError(nCode); return; }

m_pSKOrder.GetUserAccount();                    // 帳號由這裡取得為主

// 回報通道：ConnectByID 回 0 只代表請求送出去了
m_pSKReply.SKReplyLib_ConnectByID(userId);

// 真正的就緒訊號是 OnComplete —— 它代表回報回補完成
private void OnComplete(string bstrUserID)
{
    _canSendOrder = true;   // 在這之前，送單按鈕保持停用
}

重點是最後那一行的位置：「可下單」這個狀態由 OnComplete 翻開，而不是由程式啟動翻開。 在它翻開之前，送出的入口就該是停用的。

另外沿用事件執行緒那篇的紀律：送單的 COM 呼叫要留在建立 COM 物件的那條執行緒上。評估可以放背景，送出不行。細節見〈群益API 事件回呼跑在哪個執行緒〉。

事件只能掛一次

SKOrderLib 的事件不要重複掛載。

程式裡如果有「重新初始化」或「重新連線」的路徑，很容易在第二次進來時又掛一次事件——結果是同一筆回報被處理兩次。如果你的部位或委託簿是靠回報累加的，那就會累加兩倍。

這一條是實作經驗，不是官方文件的規定。 我把它寫出來是因為它的症狀很容易被誤判成「回報重複送」，但實際上是自己掛了兩次。

自己設的下單限制會把自己鎖住

最後一個跟群益API 下單初始化同樣容易忘記的東西：官方提供兩個自我保護的設定，SetMaxQty（限制量）與 SetMaxCount（限制筆數）。有三件事要一起知道，少一件就會用錯。

① 它是「每秒」的速率限制，不是累計上限。 官方說的是設定每秒委託量的限制，一秒內下單超過設定值時，該類型的下單會被鎖定。不是「今天總共只能下這麼多」。

② 鎖定與解鎖都是「該市場別」的。 參數 nMarketType 分成六種：

被鎖住之後要呼叫 UnlockOrder 解鎖，官方備註寫的是：

若下單超過設定被上鎖時，需呼叫 UnlockOrder 解鎖，才可繼續下單。

而 UnlockOrder 一樣要帶 nMarketType——解鎖是逐市場別解的。 這一點不注意，你會解錯對象，然後以為解鎖沒有用。

③ 把值設成小於等於零，代表不限制。 這是官方對參數的說明。

（至於「沒有呼叫過這兩個函式會怎樣」——那和「傳入小於等於零」是兩件不同的事，本文不把它當成官方結論。）

這個保險最容易出事的方式，是你忘了自己設過。 測試的時候設一個小數字，跑一跑就被鎖住，之後每一筆都送不出去——而你會開始查連線、查憑證、查帳號，就是不會想到是自己三天前設的那個值。

常見問題

風險揭露

期貨與選擇權屬高槓桿商品，價格波動可能造成超過原始保證金的損失，交易人須自負交易責任。本文為程式開發技術教學，說明下單前置流程與回報就緒判定，不構成投資建議，也不保證任何交易結果。程式化交易並不降低市場風險，反而可能因程式錯誤造成非預期的委託行為——在回報尚未就緒時送單、或重複掛載事件造成回報重複計算，都是這類錯誤的來源。

投資人教育資源

延伸閱讀

• 〈群益API 登入錯誤怎麼判讀〉——群益API 下單初始化沿路會遇到的 2017、1038、1000，那篇有完整判讀與分類。
• 〈群益API 事件回呼跑在哪個執行緒〉——送單為什麼不能搬到背景執行緒。
• 〈群益API 報價訂閱有哪兩層〉——訂閱附帶歷史回補，與本篇的回報回補是同一個模式。

參考資料

• SKOrderLib_Initialize、ReadCertByID、GetUserAccount 的步驟備註，OnComplete 代表回補完成，SetMaxQty／SetMaxCount 的每秒限制、市場別參數與「小於等於零不限制」，UnlockOrder 的解鎖說明，均依群益官方元件說明文件的下單準備與回報章節。
• 錯誤碼 2017／1038／1000 的常數名與說明出自官方錯誤碼表。
• 事件不可重複掛載、回報未就緒不宜送單、ConnectByID 回 0 只代表請求送出：實作歸納，非官方文件記載。

免責聲明

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