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
Common1 ~ 499
AfterMarket1 ~ 499
Odd1 ~ 999
Emg1 ~ 999, 1000 ~ 499000 (超過 1000 後,最小升降單位為 1000)
IntradayOdd1 ~ 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市場總序號