Skip to main content

Python

登入及用戶資訊​

登入 login()​

Input Parameters​

None

Response Example​

None

info

登入有效時間為一天,每日有登入次數限制。在執行任何功能之前,必須成功呼叫過一次登入。

重設密碼 reset_password()​

程式執行到此函數時,會於命令列提示請用戶輸入證券密碼及憑證密碼。

Input Parameters​

None

Response Example​

None

info

若您的證券登入密碼或憑證密碼有變更,請務必記得重設儲存在 SDK 的密碼。

caution

若密碼錯誤嘗試超過 3 次,您的證券帳號將被暫時鎖定,此時可參考 登入問題說明 進行解鎖。

憑證資訊 certinfo()​

取得憑證相關資訊。

Input Parameters​

None

Response Example​

{
"cn": "A123456789-00-00::PCC005", // 憑證名稱 (string)
"is_valid": True, // 憑證有效 (boolean)
"not_after": 1676735999, // 憑證有效期限 (timestamp)
"serial": "7DA4C168" // 憑證序號 (string)
}
info

憑證效期為自申請日起一年,請務必於憑證過期前申請展延或更換新憑證。

金鑰資訊 get_key_info()​

取得金鑰相關資訊。

Input Parameters​

None

Response Example​

{
"api_key": "XXXXXXXXXXXXX", // API 金鑰 (string)
"api_key_memo": "", // API 金鑰備註 (string)
"api_key_name": "", // API 金鑰名稱 (string)
"created_at": {"nanos": 220000000, "seconds": 1633657888}, // API 金鑰建立時間
"scope": "C", // API 金鑰權限 (KeyScope enum)
"status": 1 // API 金鑰狀態 (number)
}
info

金鑰有效期限為自建立時間起一年。

交易額度及權限 get_trade_status()​

取得用戶交易額度、交易權限相關資訊。

Input Parameters​

None

Response Example​

{
"trade_limit": 0, // 交易額度 (number)
"margin_limit": 500000, // 融資額度 (number)
"short_limit": 500000, // 融券額度 (number)
"day_trade_code": "X", // 現股當沖狀態代碼 (X:已啟用 Y:僅可先買後賣 N:未啟用 S:暫停中)
"margin_code": "0", // 融資狀態代碼 (0:可買賣 1:可買 2:可賣 9:不可買賣)
"short_code": "0" // 融券狀態代碼 (0:可買賣 1:可買 2:可賣 9:不可買賣)
}

交易下單​

下單 place_order(order_object)​

送出委託單。

Input Parameters​

參數類別說明
order_objectOrderObject委託內容

Response Example​

{
"ord_date": "20220310", // 委託日期 YYYYMMDD (string)
"ord_time": "094932438", // 委託時間 HHmmssSSS (string)
"ord_type": "2", //
"ord_no": "A4461", // 委託序號 (string)
"ret_code": "000000", // 處理結果代碼 (string)
"ret_msg": "", // 錯誤訊息 (string)
"work_date": "20220310" // 有效交易日期 (string)
}

改價 modify_price(order_result, target_price, price_flag)​

修改委託價格。

Input Parameters​

參數類別說明
order_resultOrderResult委託單資料
target_pricefloat or None目標價格
price_flag(option)PriceFlag價格旗標
info

市價不能變更為其他價格旗標,其他價格旗標也無法變更為市價

除了限價之外,其他價格旗標都不能變更為原本的價格旗標 ex: 漲停 -> 漲停, 跌停 -> 跌停

price_flag 在非限價時,target_price 要放 None

caution

提供以下範例

sdk.modify_price(order_result, 10.00) // 改成限價 10.00 元

sdk.modify_price(order_result, None, PriceFlag.LimitDown) // 改成跌停

sdk.modify_price(order_result, None, PriceFlag.LimitUp) // 改成漲停

sdk.modify_price(order_result, None, PriceFlag.Flat) // 改成平盤

Response Example​

{
"ret_code": "000000", // 處理結果代碼 (string)
"ret_msg": "", // 錯誤訊息 (string)
"ord_date": "20220310", // 修改委託日期 YYYYMMDD (string)
"ord_time": "104605207" // 修改委託時間 HHmmssSSS (string)
}
caution

只能修改 ROD 限價單的價格。

刪改單 cancel_order(order_result, **kwargs)​

減少委託單量,或刪除單筆委託。

Input Parameters​

參數類別說明
order_resultOrderResult委託單資料
cel_qtyint取消張數 (optional)
cel_qty_shareint取消股數 (optional)
info

cel_qty 或 cel_qty_share 只需要提供其中一個,系統會自動處理張/股轉換。若兩者都沒有提供,系統會刪除該筆委託。

Response Example​

{
"ret_code": "000000", // 處理結果代碼 (string)
"ret_msg": "", // 錯誤訊息 (string)
"ord_date": "20220310", // 刪除委託日期 YYYYMMDD (string)
"ord_time": "101825110" // 刪除委託時間 HHmmssSSS (string)
}

委託紀錄 get_order_results()​

取得委託列表。

Input Parameters​

None

Response Example​

[{
"ap_code": "1", // 盤別 (APCode enum)
"avg_price": 0.0, // 成交均價 (number)
"bs_flag": "R", // 委託條件 (BSFlag enum)
"buy_sell": "B", // 買賣別 (Action enum)
"cel_qty": 1, // 已取消數量(張) (number)
"cel_qty_share": 1000, // 已取消數量(股) (number)
"celable": "2", // 可取消狀態 1:可取消 2:不可取消 (string)
"err_code": "00000000", // 錯誤碼 (string)
"err_msg": "", // 錯誤訊息 (string)
"mat_qty": 0, // 已成交數量(張) (number)
"mat_qty_share": 0, // 已成交數量(股) (number)
"od_price": 25.95, // 委託價格 (number)
"ord_date": "20220310", // 原始委託日期 (string)
"ord_no": "A4461", // 委託書編號 (string)
"ord_status": "2", // 預約狀態 1:預約單 2:盤中單 (string)
"ord_time": "094932438", // 原始委託時間 (string)
"org_qty": 1, // 原始委託數量(張) (number)
"org_qty_share": 1000, // 原始委託數量(股) (number)
"pre_ord_no": "", // 預約單編號,預約單時才有值 (string)
"price_flag": "2", // 價格旗標 (PriceFlag enum)
"stock_no": "2884", // 股票代號 (string)
"trade": "0", // 交易類別 (Trade enum)
"work_date": "20220310", // 有效交易日期 (string)
"user_def": "下單測試" // 自訂欄位 (string)
}, ...]

歷史委託 get_order_results_by_date(start_date, end_date)​

取得 start_date, end_date 時間範圍內的歷史委託列表,無法查詢已刪除及預約單。

PriceFlag 只有判斷市價及限價

Input Parameters​

參數類別說明
start_datestring格式為 yyyy-MM-dd 的開始日期
end_datestring格式為 yyyy-MM-dd 的結束日期

取得特定日期區間的歷史委託列表,目前提供查詢的日期範圍,以 180 日為限!

若超過這個時間範圍區間,會得到 AW00003 的錯誤訊息!

Response Example​

[{
"ack_date": "20230310", //委託日期
"ap_code": "1", // 盤別 (APCode enum)
"avg_price": 0.0, // 成交均價 (number)
"bs_flag": "R", // 委託條件 (BSFlag enum)
"buy_sell": "B", // 買賣別 (Action enum)
"cel_qty": 1, // 已取消數量(張) (number)
"cel_qty_share": 1000, // 已取消數量(股) (number)
"celable": "2", // 可取消狀態 1:可取消 2:不可取消 (string)
"mat_qty": 0, // 已成交數量(張) (number)
"mat_qty_share": 0, // 已成交數量(股) (number)
"od_price": 25.95, // 委託價格 (number)
"ord_date": "20220310", // 原始委託日期 (string)
"ord_no": "A4461", // 委託書編號 (string)
"ord_time": "094932438", // 原始委託時間 (string)
"org_qty": 1, // 原始委託數量(張) (number)
"org_qty_share": 1000, // 原始委託數量(股) (number)
"price_flag": "0", // 價格旗標 (PriceFlag enum),現階段只能判斷限價(limit)與市價(market)
"stock_no": "2884", // 股票代號 (string)
"trade": "0", // 交易類別 (Trade enum)
"user_def": "下單測試" // 自訂欄位 (string)
}, ...]

市場開盤狀態 get_market_status()​

取得開盤狀態。

Input Parameters​

None

Response Example​

{
"is_trading_day": true, //當日是否開盤
"last_trading_day": "20221017", //上個交易日期
"next_trading_day": "20221019" //下個交易日期
}

取得機器時間 get_machine_time()​

取得主機端機器的時間

Input Parameters​

None

Response Example​

{
"time": "2022-03-10 10:23:48.464" // 機器時間 (string)
}
caution

若您的下單程式所在的機器時間與主機時間相差過多,有可能導致下單驗證失敗,建議定時與主機進行校時同步。


帳務查詢​

近期成交明細 get_transactions(query_range)​

取得近期特定時間範圍內的成交明細。

Input Parameters​

參數類別說明
query_rangestring時間區間,目前有效數值為 "0d"(當日)、"3d"、"1m"、"3m"

Response Example​

[{ // 成交明細彙總 (array)
"buy_sell": "S",
"c_date": "20220314",
"cost": "-16410", // 已實現損益成本小計
"make": "7933",
"make_per": "48.34",
"mat_dats": [{ // 成交明細 (array)
"buy_sell": "S",
"c_date": "20220314",
"db_fee": "0", // 融券手續費
"fee": "34", // 手續費 (string)
"make": "7933", // 已實現損益
"make_per": "48.34", // 已實現獲利率
"order_no": "A7828002924570", // 前 5 碼由委託列表的委託書號 (ord_no) 所組成
"pay_n": "24343", // 淨收付款 (string)
"price": "24.45", // 成交價格 (string)
"price_qty": "24450", // 價金 (string)
"qty": "1000", // 成交數量 (string)
"s_type": "H", // 市場別 H:上市,O:上櫃,R:興櫃
"stk_na": "玉山金",
"stk_no": "2884",
"t_date": "20220310", // 成交日期 (string)
"t_time": "090819800", // 成交時間 (string) -> 僅成交當日有資料,其餘時間皆為空值
"tax": "73", // 交易稅 (string)
"tax_g": "0", // 證所稅 (string)
"trade": "0", // 交易類別 (Trade enum)
"user_def": "下單測試" // 自訂欄位 (string)
}],
"price_avg": "24.45", // 成交均價 (string)
"price_qty": "24450", // 價金小計 (string)
"qty": "1000",
"recv": "24343", // 已實現損益收入小計
"s_type": "H", // 市場別 H:上市 O:上櫃 R:興櫃
"stk_na": "玉山金",
"stk_no": "2884",
"t_date": "20220310",
"trade": "0"
}, ...]

成交明細(依指定日期) get_transactions_by_date(start_date, end_date)​

取得 start_date, end_date 時間範圍內的成交明細。

Input Parameters​

參數類別說明
start_datestring格式為 yyyy-MM-dd 的開始日期
end_datestring格式為 yyyy-MM-dd 的結束日期

取得特定日期區間的成交明細,目前提供查詢的日期範圍,以 180 日為限!

若超過這個時間範圍區間,會得到 AW00002 的錯誤訊息!

Response Example​

[{ // 成交明細彙總 (array)
"buy_sell": "S",
"c_date": "20220314",
"cost": "-16410", // 已實現損益成本小計
"make": "7933",
"make_per": "48.34",
"mat_dats": [{ // 成交明細 (array)
"buy_sell": "S",
"c_date": "20220314",
"db_fee": "0", // 融券手續費
"fee": "34", // 手續費 (string)
"make": "7933", // 已實現損益
"make_per": "48.34", // 已實現獲利率
"order_no": "A7828002924570", // 前 5 碼由委託列表的委託書號 (ord_no) 所組成
"pay_n": "24343", // 淨收付款 (string)
"price": "24.45", // 成交價格 (string)
"price_qty": "24450", // 價金 (string)
"qty": "1000", // 成交數量 (string)
"s_type": "H", // 市場別 H:上市,O:上櫃,R:興櫃
"stk_na": "玉山金",
"stk_no": "2884",
"t_date": "20220310", // 成交日期 (string)
"t_time": "090819800", // 成交時間 (string) -> 僅成交當日有資料,其餘時間皆為空值
"tax": "73", // 交易稅 (string)
"tax_g": "0", // 證所稅 (string)
"trade": "0", // 交易類別
"user_def": "下單測試" // 自訂欄位 (string)
}],
"price_avg": "24.45", // 成交均價 (string)
"price_qty": "24450", // 價金小計 (string)
"qty": "1000",
"recv": "24343", // 已實現損益收入小計
"s_type": "H", // 市場別 H:上市 O:上櫃 R:興櫃
"stk_na": "玉山金",
"stk_no": "2884",
"t_date": "20220310",
"trade": "0" // 交易類別
}, ...]

庫存明細 get_inventories()​

取得當下的庫存明細。

Input Parameters​

None

Response Example​

[{ // 庫存彙總
"ap_code": "", // 盤別,僅盤中零股會有值 (string)
"cost_qty": "1150", // 成本股數
"cost_sum": "-103235", // 成本總計
"make_a_per": "51.59", // 未實現獲利率
"make_a_sum": "53255", // 未實現損益小計
"price_avg": "89.63", // 成交均價
"price_evn": "89.99", // 損益平衡價
"price_mkt": "136.45", // 即時價格(無假除權息)
"price_now": "136.45", // 即時價格(有假除權息)
"price_qty_sum": "103074", // 價金總計
"qty_b": "0", // 今委買股數
"qty_bm": "0", // 今委買成交股數
"qty_c": "0", // 調整股數(現償 or 匯撥) 負號為減庫存
"qty_l": "1150", // 昨餘額股數
"qty_s": "0", // 今委賣股數
"qty_sm": "0", // 今委賣成交股數
"rec_va_sum": "156490", // 未實現收入小計
"s_type": "H", // 市場別 H:上市 O:上櫃 R:興櫃
"stk_dats": [{ // 庫存明細
"buy_sell": "B",
"cost_r": "0", // 已分攤成本
"fee": "18", // 手續費(由原始資料分攤)
"make_a": "804", // 未實現損益
"make_a_per": "6.28", // 未實現獲益率
"ord_no": "D3660038938518", // 前 5 碼由委託列表的委託書號 (ord_no) 所組成
"pay_n": "-12808", // 淨收付金額(由原始資料分攤)
"price": "127.90", // 成交價格
"price_evn": "128.41", // 平衡損益價(以cost-costr計算)
"qty": "100", // 庫存股數
"qty_c": "0", // 調整股數(現償 or 匯撥) 負號為減庫存
"qty_h": "0", // 實高權值股數(維持率)
"qty_r": "0", // 已分攤股數
"t_date": "20210512", // 成交日期
"t_time": "", // 成交時間 -> 僅成交當日有資料,其餘時間皆為空值
"tax": "0", // 交易稅(由原始資料分攤)
"tax_g": "0", // 證所稅(由原始資料分攤)
"trade": "0", // 交易類別
"value_mkt": "13645", // 市值(無假除權息)
"value_now": "13645", // 市值(有假除權息)
"user_def": "下單測試" // 自訂欄位
}],
"stk_na": "元大台灣50", // 股票名稱
"stk_no": "0050", // 股票代碼
"trade": "0", // 交易類別
"value_mkt": "13645", // 市值(無假除權息)
"value_now": "13645" // 市值(有假除權息)
}, ...]

銀行餘額 get_balance()​

取得銀行餘額相關資訊。 (每 180 秒可查詢一次)

Input Parameters​

None

Response Example​

{
"available_balance": 500000, // 可用銀行餘額 (number)
"exange_balance": 100000, //今日票據交換金額 (number)
"stock_pre_save_amount": 100000 //圈存金額 (number)
}

交割款 get_settlements()​

取得交割款資訊。

Input Parameters​

None

Response Example​

[{
"c_date": "20220310", // 交割日期 YYYYMMDD (string)
"date": "20220308", // 成交日期 YYYYMMDD (string)
"price": "-80912" // 交割款應收金額 (string)
}, {
"c_date": "20220311",
"date": "20220309",
"price": "4826"
}, ...]
caution

交易當日盤中取得的交割款為試算結果,僅供參考,需待當日 21:00 帳務系統更新後,才可取得正確的 T+2 交割金額。


Decorators​

委託回報 on('order')​

委託回報透過 decorator 的 callback function 回傳委託資訊。

Input Parameters​

參數類別說明
notify_ackNotifyAck委託內容

成交回報 on('dealt')​

成交回報透過 decorator 的 callback function 回傳成交資訊。

Input Parameters​

參數類別說明
notify_dealtNotifyDealt成交內容

錯誤回報 on('error')​

當發生錯誤時會回傳相關資訊。

Classes​

OrderObject​

ParameterTypeDefault ValueMeaning
ap_codeAPCodeAPCode.Common盤別
buy_sellAction-買賣別
pricefloat-委託價格
stock_nostring-股票代號
quantityint-委託數量
price_flagPriceFlagPriceFlag.Limit價格旗標
bs_flagBSFlagBSFlag.ROD委託條件
tradeTradeTrade.Cash交易類別
user_def (optional)string-自訂欄位(長度最長 50 字元以下,不支援特殊符號)( 模擬環境不適用 )
caution

不同 apCode 對應的 quantity 之單位及範圍不同,請參考 盤別 說明。

caution

當 apCode 爲 APCode.Common, APCode.Odd, APCode.Emg, APCode.IntradayOdd 其中之一,且 priceFlag 爲 PriceFlag.Limit 時,需填入 price 欄位,其餘時候 price 欄位不需填入。

OrderResult​

委託列表,透過 get_order_results() 取得。

ParameterTypeMeaning
ap_codeAPCode盤別
avg_pricenumber成交均價
bs_flagBSFlag委託條件
buy_sellAction買賣別
cel_qtynumber已取消數量(張)
cel_qty_sharenumber已取消數量(股)
celablestring可取消狀態 1:可取消 2:不可取消
err_codestring錯誤碼
err_msgstring錯誤訊息
mat_qtynumber已成交數量(張)
mat_qty_sharenumber已成交數量(股)
od_pricenumber委託價格
ord_datestring原始委託日期
ord_nostring委託書編號
ord_statusstring預約狀態 1:預約單 2:盤中單
ord_timestring原始委託時間
org_qtynumber原始委託數量(張)
org_qty_sharenumber原始委託數量(股)
pre_ord_nostring預約單編號,預約單時才有值
price_flagPriceFlag價格旗標
stock_nostring股票代號
tradeTrade交易類別
work_datestring有效交易日期
user_defstring自訂欄位 ( 模擬環境不適用 )

Constants​

Action​

買賣別

NameValueMeaning
Buy"B"買
Sell"S"賣

APCode​

盤別

NameValueMeaning
Common"1"整股
AfterMarket"2"盤後定價
Odd"3"盤後零股
Emg"4"興櫃
IntradayOdd"5"盤中零股

使用不同 APCode 時,相對應的 Quantity 欄位所代表的單位及範圍也會不同,詳如下表:

APCode NamesQuantity UnitQuantity Ranges
Common張1 ~ 499
AfterMarket張1 ~ 499
Odd股1 ~ 999
Emg股1 ~ 999, 1000 ~ 499000 (超過 1000 後,最小升降單位為 1000)
IntradayOdd股1 ~ 999

使用不同 APCode 時,可使用的 PriceFlag 會不同,詳如下表:

APCode NamesAvailable PriceFlag Names
CommonLimit, Flat, LimitDown, LimitUp, Market
AfterMarketLimit
OddLimit, Flat, LimitDown, LimitUp
EmgLimit
IntradayOddLimit, Flat, LimitDown, LimitUp

Trade​

交易類別

NameValueMeaning
Cash"0"現股
Margin"3"融資
Short"4"融券
DayTrading"9"信用當沖(僅適用於帳務)
DayTradingSell"A"現股當沖賣

PriceFlag​

價格旗標

NameValueMeaning
Limit"0"限價
Flat"1"平盤
LimitDown"2"跌停
LimitUp"3"漲停
Market"4"市價

BSFlag​

委託條件

NameValueMeaning
FOK"F"立即全部成交否則取消
IOC"I"立即成交否則取消
ROD"R"當日委託有效單

KeyScope​

API 金鑰權限

NameValueMeaning
Trade"A"下單
Query"B"查詢
All"C"全部

NotifyAck​

委託回報的物件

ParameterTypeMeaning
work_datestring有效交易日期
ret_datestring委託日期
ret_timestring委託時間
ord_statusstring預約狀態 1:預約單 2:盤中單
ord_nostring委託書編號
pre_ord_nostring預約單編號,預約單時才有值
stock_nostring股票代號
buy_sellstring買賣別
ap_codestring盤別
price_flagstring價格旗標
tradestring交易類別
od_pricestring委託價格
org_qtystring原始委託數量
mat_qtystring已成交數量
cel_qtystring已取消數量
cel_typestring可取消狀態 1 可取消 2 不可取消
err_codestring錯誤碼
err_msgstring錯誤訊息
before_qtystring變更前數量
after_qtystring變更後數量
bs_flagstring委託條件

NotifyDealt​

成交回報的物件

ParameterTypeMeaning
mat_timestring成交時間
ord_nostring委託書編號
stock_nostring股票代號
buy_sellstring買賣別
ap_codestring盤別
tradestring交易類別
mat_pricestring成交價格
mat_qtystring已成交數量
pay_pricestring價金
mkt_seq_numstring市場總序號