Python
登入及用戶資訊
登入 login()
Input Parameters
None
Response Example
None
登入有效時間為一天,每日有登入次數限制。在執行任何功能之前,必須成功呼叫過一次登入。
重設密碼 reset_password()
程式執行到此函數時,會於命令列提示請用戶輸入證券密碼及憑證密碼。
Input Parameters
None
Response Example
None
若您的證券登入密碼或憑證密碼有變更,請務必記得重設儲存在 SDK 的密碼。
若密碼錯誤嘗試超過 3 次,您的證券帳號將被暫時鎖定,此時可參考 登入問題說明 進行解鎖。
憑證資訊 certinfo()
取得憑證相關資訊。
Input Parameters
None
Response Example
{
"cn": "A123456789-00-00::PCC005", // 憑證名稱 (string)
"is_valid": True, // 憑證有效 (boolean)
"not_after": 1676735999, // 憑證有效期限 (timestamp)
"serial": "7DA4C168" // 憑證序號 (string)
}
憑證效期為自申請日起一年,請務必於憑證過期前申請展延或更換新憑證。
金鑰資訊 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)
}
金鑰有效期限為自建立時間起一年。
交易額度及權限 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_object | OrderObject | 委託內容 |
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_result | OrderResult | 委託單資料 |
target_price | float or None | 目標價格 |
price_flag(option) | PriceFlag | 價格旗標 |
市價不能變更為其他價格旗標,其他價格旗標也無法變更為市價
除了限價之外,其他價格旗標都不能變更為原本的價格旗標 ex: 漲停 -> 漲停, 跌停 -> 跌停
price_flag 在非限價時,target_price 要放 None
提供以下範例
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)
}
只能修改 ROD 限價單的價格。
刪改單 cancel_order(order_result, **kwargs)
減少委託單量,或刪除單筆委託。
Input Parameters
參數 | 類別 | 說明 |
---|---|---|
order_result | OrderResult | 委託單資料 |
cel_qty | int | 取消張數 (optional) |
cel_qty_share | int | 取消股數 (optional) |
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_date | string | 格式為 yyyy-MM-dd 的開始日期 |
end_date | string | 格式為 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)
}
若您的下單程式所在的機器時間與主機時間相差過多,有可能導致下單驗證失敗,建議定時與主機進行校時同步。
帳務查詢
近期成交明細 get_transactions(query_range)
取得近期特定時間範圍內的成交明細。
Input Parameters
參數 | 類別 | 說明 |
---|---|---|
query_range | string | 時間區間,目前有效數值為 "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_date | string | 格式為 yyyy-MM-dd 的開始日期 |
end_date | string | 格式為 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"
}, ...]
交易當日盤中取得的交割款為試算結果,僅供參考,需待當日 21:00 帳務系統更新後,才可取得正確的 T+2 交割金額。
Decorators
委託回報 on('order')
委託回報透過 decorator 的 callback function 回傳委託資訊。
Input Parameters
參數 | 類別 | 說明 |
---|---|---|
notify_ack | NotifyAck | 委託內容 |
成交回報 on('dealt')
成交回報透過 decorator 的 callback function 回傳成交資訊。
Input Parameters
參數 | 類別 | 說明 |
---|---|---|
notify_dealt | NotifyDealt | 成交內容 |
錯誤回報 on('error')
當發生錯誤時會回傳相關資訊。
Classes
OrderObject
Parameter | Type | Default Value | Meaning |
---|---|---|---|
ap_code | APCode | APCode.Common | 盤別 |
buy_sell | Action | - | 買賣別 |
price | float | - | 委託價格 |
stock_no | string | - | 股票代號 |
quantity | int | - | 委託數量 |
price_flag | PriceFlag | PriceFlag.Limit | 價格旗標 |
bs_flag | BSFlag | BSFlag.ROD | 委託條件 |
trade | Trade | Trade.Cash | 交易類別 |
user_def (optional) | string | - | 自訂欄位(長度最長 50 字元以下,不支援特殊符號) |
不同 apCode 對應的 quantity 之單位及範圍不同,請參考 盤別 說明。
當 apCode 爲 APCode.Common, APCode.Odd, APCode.Emg, APCode.IntradayOdd 其中之一,且 priceFlag 爲 PriceFlag.Limit 時,需填入 price 欄位,其餘時候 price 欄位不需填入。
OrderResult
委託列表,透過 get_order_results()
取得。
Parameter | Type | Meaning |
---|---|---|
ap_code | APCode | 盤別 |
avg_price | number | 成交均價 |
bs_flag | BSFlag | 委託條件 |
buy_sell | Action | 買賣別 |
cel_qty | number | 已取消數量(張) |
cel_qty_share | number | 已取消數量(股) |
celable | string | 可取消狀態 1:可取消 2:不可取消 |
err_code | string | 錯誤碼 |
err_msg | string | 錯誤訊息 |
mat_qty | number | 已成交數量(張) |
mat_qty_share | number | 已成交數量(股) |
od_price | number | 委託價格 |
ord_date | string | 原始委託日期 |
ord_no | string | 委託書編號 |
ord_status | string | 預約狀態 1:預約單 2:盤中單 |
ord_time | string | 原始委託時間 |
org_qty | number | 原始委託數量(張) |
org_qty_share | number | 原始委託數量(股) |
pre_ord_no | string | 預約單編號,預約單時才有值 |
price_flag | PriceFlag | 價格旗標 |
stock_no | string | 股票代號 |
trade | Trade | 交易類別 |
work_date | string | 有效交易日期 |
user_def | string | 自訂欄位 |
Constants
Action
買賣別
Name | Value | Meaning |
---|---|---|
Buy | "B" | 買 |
Sell | "S" | 賣 |
APCode
盤別
Name | Value | Meaning |
---|---|---|
Common | "1" | 整股 |
AfterMarket | "2" | 盤後定價 |
Odd | "3" | 盤後零股 |
Emg | "4" | 興櫃 |
IntradayOdd | "5" | 盤中零股 |
使用不同 APCode 時,相對應的 Quantity 欄位所代表的單位及範圍也會不同,詳如下表:
APCode Names | Quantity Unit | Quantity Ranges |
---|---|---|
Common | 張 | 1 ~ 499 |
AfterMarket | 張 | 1 ~ 499 |
Odd | 股 | 1 ~ 999 |
Emg | 股 | 1 ~ 999, 1000 ~ 499000 (超過 1000 後,最小升降單位為 1000) |
IntradayOdd | 股 | 1 ~ 999 |
使用不同 APCode 時,可使用的 PriceFlag 會不同,詳如下表:
APCode Names | Available PriceFlag Names |
---|---|
Common | Limit, Flat, LimitDown, LimitUp, Market |
AfterMarket | Limit |
Odd | Limit, Flat, LimitDown, LimitUp |
Emg | Limit |
IntradayOdd | Limit, Flat, LimitDown, LimitUp |
Trade
交易類別
Name | Value | Meaning |
---|---|---|
Cash | "0" | 現股 |
Margin | "3" | 融資 |
Short | "4" | 融券 |
DayTrading | "9" | 信用當沖(僅適用於帳務) |
DayTradingSell | "A" | 現股當沖賣 |
PriceFlag
價格旗標
Name | Value | Meaning |
---|---|---|
Limit | "0" | 限價 |
Flat | "1" | 平盤 |
LimitDown | "2" | 跌停 |
LimitUp | "3" | 漲停 |
Market | "4" | 市價 |
BSFlag
委託條件
Name | Value | Meaning |
---|---|---|
FOK | "F" | 立即全部成交否則取消 |
IOC | "I" | 立即成交否則取消 |
ROD | "R" | 當日委託有效單 |
KeyScope
API 金鑰權限
Name | Value | Meaning |
---|---|---|
Trade | "A" | 下單 |
Query | "B" | 查詢 |
All | "C" | 全部 |
NotifyAck
委託回報的物件
Parameter | Type | Meaning |
---|---|---|
work_date | string | 有效交易日期 |
ret_date | string | 委託日期 |
ret_time | string | 委託時間 |
ord_status | string | 預約狀態 1:預約單 2:盤中單 |
ord_no | string | 委託書編號 |
pre_ord_no | string | 預約單編號,預約單時才有值 |
stock_no | string | 股票代號 |
buy_sell | string | 買賣別 |
ap_code | string | 盤別 |
price_flag | string | 價格旗標 |
trade | string | 交易類別 |
od_price | string | 委託價格 |
org_qty | string | 原始委託數量 |
mat_qty | string | 已成交數量 |
cel_qty | string | 已取消數量 |
cel_type | string | 可取消狀態 1 可取消 2 不可取消 |
err_code | string | 錯誤碼 |
err_msg | string | 錯誤訊息 |
before_qty | string | 變更前數量 |
after_qty | string | 變更後數量 |
bs_flag | string | 委託條件 |
NotifyDealt
成交回報的物件
Parameter | Type | Meaning |
---|---|---|
mat_time | string | 成交時間 |
ord_no | string | 委託書編號 |
stock_no | string | 股票代號 |
buy_sell | string | 買賣別 |
ap_code | string | 盤別 |
trade | string | 交易類別 |
mat_price | string | 成交價格 |
mat_qty | string | 已成交數量 |
pay_price | string | 價金 |
mkt_seq_num | string | 市場總序號 |