Skip to main content

Python

Functions​

certinfo()​

取得憑證相關資訊。

Input Parameters​

None

Response Example​

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

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

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_balance()​

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

Input Parameters​

None

Response Example​

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

get_market_status()​

取得開盤狀態。

Input Parameters​

None

Response Example​

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

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)
}, ...]


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)
}, ...]

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:不可買賣)
}

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)
    }],
    "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"  // 交易類別
    }],
    "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" // 市值(有假除權息)
    }],
    "stk_na": "元大台灣50", // 股票名稱
    "stk_no": "0050", // 股票代碼
    "trade": "0", // 交易類別
    "value_mkt": "13645", // 市值(無假除權息)
    "value_now": "13645" // 市值(有假除權息)
}, ...]

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 交割金額。

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_machine_time()​

取得主機端的時間

Input Parameters​

None

Response Example​

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

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

login()​

登入

Input Parameters​

None

Response Example​

None

info

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

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 限價單的價格。

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)
}

reset_password()​

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

Input Parameters​

None

Response Example​

None

info

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

caution

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

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交易類別
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有效交易日期

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市場總序號
Last updated on