群益API 測試環境是什麼？SetAuthority 的位元旗標與正式環境

範例程式在登入前呼叫了 SKCenterLib_SetAuthority，但不知道這行在做什麼。官方函式表的摘要只寫了 SGX 專線的 0／1，看起來是個開關，範例裡卻出現 2 和 3。另外聽說群益API 有測試環境，想找一個不會真的下單的測試方法。

群益API 測試環境的關鍵在一句話：SetAuthority 的參數不是開關，而是兩個位元；預設是正式環境。

本文依官方說明與官方範例程式，整理這個參數的四個選項；想要不會真的下單的測試，最後一節說明怎麼在自己的程式裡做模擬開關。

SetAuthority 的參數為什麼不是 0／1 開關？

先看官方說明文件的原文：

• 說明：「(SGX 專線only)手動設定特殊功能屬性開啟或關閉。」
• 宣告：Long SKCenterLib_SetAuthority([in] LONG nAuthorityFlag);
• 參數 nAuthorityFlag：「指定特殊功能屬性是否開啟或關閉」
• 回傳值：「0表示初始化成功，其餘非0數值都表示失敗。錯誤代碼可參考對照表。」

備註有三行，依原文順序是：

1. 「SGX 專線屬性：關閉／開啟：0／1」
2. 「Bit 1為環境設定：預設0，代表正式環境」
3. 「一般客戶可忽略此部分」

函式表的摘要只寫了 SGX 那一位，完整的說明在這一節：這個參數其實是兩個位元。 官方 C# 範例程式的註解也寫得很清楚：「//SGX 專線屬性：bit 0:關閉／開啟(0／1)；bit 1 環境切換」。範例的下拉選單有四個選項：

最低的位元（bit 0）是 SGX 專線的屬性，屬於特定的專線服務，本文不展開。

群益API 預設是哪個環境？

正式環境。官方的說明是「Bit 1為環境設定：預設0，代表正式環境」；官方範例的下拉選單，預設選的也是「正式環境」。

在正式環境送出的委託，就是真的委託。

群益API 測試環境給誰用？

官方備註的第三行是「一般客戶可忽略此部分」，這一行排在環境設定那一行之後。

測試環境能不能用、怎麼開通，屬於帳戶側的設定。如果有遇到這類的問題可以先跟您的營業員反應。

另外，本文不描述測試環境的交易行為，例如委託會送到哪裡、會不會成交，我們沒有這方面的紀錄。登入回傳值的判讀，見〈群益API 登入錯誤怎麼判讀〉。

SetAuthority 什麼時候呼叫？

官方範例都在登入之前呼叫 SetAuthority：舊版範例在登入按鈕的處理裡，先呼叫 SetAuthority、再呼叫 SKCenterLib_Login；新版範例則讓使用者在登入前從下拉選單選好環境。

放進〈群益API 的六個 COM 物件各管什麼〉的流程，就是：建立物件 → 掛事件 →（要切換環境時）SetAuthority → Login。

登入之後再改會怎樣，我們沒有測過。回傳值非 0 時，用 SKCenterLib_GetReturnCodeMessage 查官方的說明文字。

想要不會真的下單的測試：程式層的模擬開關

測試環境是官方元件的一個環境設定，它的性質官方沒有說明，我們也沒有紀錄。想要確保「不會真的下單」，完全由自己掌握的做法是在自己的程式裡做模擬開關：

1. 程式裡有一個全域的「模擬／真單」開關，預設是模擬。
2. 模擬時，在呼叫下單函式之前攔截：不呼叫下單函式，回給上層一個假的委託序號，並記錄「這是模擬單」。
3. 刪單、改單在模擬時直接拒絕，或只處理模擬單，避免以為真的委託已經刪掉。
4. 切到真單要有明確的動作，例如在設定檔加上啟動時的確認步驟；不能因為重開程式就回到真單。

這是通用的工程做法，換成任何下單 API 都適用。

SetAuthority 與模擬開關程式碼

下面的片段示範兩件事：nAuthorityFlag 的位元組法，以及模擬開關的最小骨架。片段接在〈群益API Python 入門〉的範例之後使用：

# 群益API SetAuthority：nAuthorityFlag 是兩個位元
ENV_TEST = 0b10      # bit 1：環境（0 正式、1 測試）
SGX_LINE = 0b01      # bit 0：SGX 專線屬性

flag = 0             # 正式環境、不開 SGX 專線（官方範例的預設選項）
code = center.SKCenterLib_SetAuthority(flag)          # 官方範例在登入前呼叫
print("SetAuthority", code, center.SKCenterLib_GetReturnCodeMessage(code))


# 程式層的模擬開關：預設模擬，模擬時根本不呼叫下單函式
SIMULATION = True


def send_order(order_lib, login_id, order_obj):
    if SIMULATION:
        print("模擬單，未送出")
        return 0, "SIM-0001"          # 假的委託序號，上層要能分辨這是模擬單
    return order_lib.SendFutureOrderCLR(login_id, False, order_obj)


def cancel_order(*args):
    if SIMULATION:
        raise RuntimeError("模擬模式下不送刪單")   # 避免以為真委託已經刪掉
    ...

幾點說明：

• ENV_TEST、SGX_LINE 只是幫你看懂位元，片段實際送出的是 0，也就是正式環境。
• 模擬開關的回傳格式只是示意；SendFutureOrderCLR 真正的回傳形態，見〈群益API 下單回傳 980 怎麼讀〉。
• cancel_order 的 ... 是真單的路徑，由你自己補上。

群益API 測試環境的 3 個誤解

1. 誤解： SetAuthority 是 0／1 的開關。其實： 官方說明它有兩個位元，bit 0 是 SGX 專線屬性，bit 1 是環境設定。
2. 誤解： 群益API 的下單全部都是真單。其實： 官方元件有環境設定，預設是正式環境；正式環境下送出的委託就是真的委託。
3. 誤解： 切到測試環境就等於模擬下單。其實： 測試環境是官方元件的一個環境設定，性質官方沒有說明；要確保不會真的下單，在自己的程式裡做模擬開關。

常見問題

風險揭露

期貨與選擇權屬高槓桿商品，價格波動可能造成超過原始保證金的損失，交易人須自負交易責任。本文為程式開發技術教學，說明群益API 的環境設定與程式層模擬開關的做法，不構成投資建議，也不保證任何交易結果。程式化交易並不降低市場風險，在正式環境送出的委託就是真的委託，正式使用前請先確認程式的模擬開關與環境設定。

投資人教育資源

延伸閱讀

• 〈群益API 是什麼〉——開始寫程式前必須知道的 5 個前提。
• 〈群益API 登入錯誤怎麼判讀〉——登入回傳值的判讀。
• 〈群益API Python 入門〉——從安裝到收到第一筆報價。
• 〈群益API 的六個 COM 物件各管什麼〉——登入前後的初始化順序。

參考資料

• SKCenterLib_SetAuthority 的說明、宣告、參數、回傳值與備註，依群益官方元件說明文件。
• 四個選項的名稱與數值、在登入前呼叫的順序，依群益官方範例程式。
• 程式層模擬開關：通用的工程做法，非官方文件記載。

免責聲明

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