一、元大 Spark API 說明

本文件提供以 Python 語言使用 YuantaSparkAPI 之基本範例，在正式環境進行下單及收委成回報的簡單範例程式，並包含其他功能之使用寫法供參考，協助開發者快速上手。

YuantaSparkAPI 使用方式為讀取 C# 元件 YuantaSparkAPI.dll 以執行 API 呼叫。由於 Python 無法直接載入 C# 元件，故需使用外部套件達成元件引用。本範例使用 pythonnet 套件，使 Python 程式可呼叫 .NET 元件，達成 API 測試與功能開發。

執行環境需求

  1. 建議 Python 版本為 3.8 以上。
  2. 使用 pythonnet 套件：
pip install pythonnet

YSendOrder.py 為使用 pythonnet 之範例程式，於 Python 環境內安裝即可直接執行 .py 檔。

二、環境建置

1. 安裝 .NET SDK 8.0

下載 .NET 8.0 頁面

  • 點擊執行安裝檔。

安裝流程畫面 1 安裝流程畫面 2 安裝流程畫面 3

  • 至選擇的安裝路徑確認是否有 dotnet 資料夾。

確認 dotnet 資料夾

  • 確認 dotnet 版本是否安裝正確。

確認 dotnet 版本

2. 安裝 Python（若已安裝可省略）

Python 下載頁面 1 Python 下載頁面 2

  • 若下載時未勾選「Add python.exe to PATH」，可手動將路徑加入 PATH。

  • 確認安裝位置，於 CMD 執行：

where python

where python 結果

  1. 新增安裝路徑至 PATH。

新增 PATH 步驟 1 新增 PATH 步驟 2 新增 PATH 步驟 3

3. 安裝 pythonnet 套件

  1. 確認 Python 環境是否安裝 pip：
pip --version

確認 pip 版本

  1. 安裝 pythonnet 套件：
pip install pythonnet

安裝 pythonnet

三、範例程式操作說明

(一) Windows

1. 測試環境憑證匯入

安裝憑證步驟 1

  • 安裝測試憑證在目前帳號上。

安裝憑證步驟 2

  • 開放系統允許安裝更新憑證。

安裝憑證步驟 3

  • 安裝更新憑證。

安裝憑證步驟 4

  • 憑證安裝密碼：yuanta。

安裝憑證步驟 5

  • 憑證安裝作業。

安裝憑證步驟 6

  • 完成憑證安裝作業。

安裝憑證完成

2. 主程式 YSendOrder.py

  • 編輯與確認範例程式（元件引用路徑與範例程式路徑相同）。

編輯範例程式

  • 使用 load 函數載入 .NET Core / 8 執行環境：
load("coreclr")
  • 讓 Python 可使用 .NET 類別（例如 System.Collections.Generic.List），並設定 DLL 路徑，確保 Python 可找到同資料夾下的 YuantaSparkAPI.dll：
import clr
import System
clr.AddReference('System.Collections')
from System.Collections.Generic import List
sys.path.append(Path(pathlib.Path(__file__).parent.resolve()))
os.add_dll_directory(Path(pathlib.Path(__file__).parent.resolve()))
  • 嘗試載入 YuantaSparkAPI.dll：
try:
    clr.AddReference("YuantaSparkAPI")
except Exception as e:
    print(f"Error loading YuantaSparkAPI: {e}")
  • 點擊執行範例程式，即可執行連線、登入、下單並收到即時回報資訊。
  • 請確保所有元件與主程式（YSendOrder.py）位於同一目錄或指定路徑。

執行範例程式

  • 程式下單部分為 send_stock_order()，可更換股票代碼與下單股數。詳細內容可參考國內證券下單。

下單範例

  • 報價表部分為 ReadWatchListAll_api()，提供股票價格等當前資訊，可自行增加股票名單。詳細內容可參考報價表查詢。

報價表範例

(二) macOS

主程式 YSendOrder.py

  • 編輯與確認範例程式。

macOS 編輯範例程式

  • 使用 load 函數載入 .NET Core / 8 執行環境：
load("coreclr")
  • 讓 Python 可使用 .NET 類別（例如 System.Collections.Generic.List），並設定 DLL 路徑（macOS 需指定路徑），確保可找到 YuantaSparkAPI.dll：
import clr
import System
clr.AddReference('System.Collections')
from System.Collections.Generic import List
os.add_dll_directory(指定的絕對路徑)
  • 嘗試載入 YuantaSparkAPI.dll：
try:
    clr.AddReference("YuantaSparkAPI")
except Exception as e:
    print(f"Error loading YuantaSparkAPI: {e}")
  • 調整登入寫法：macOS 需指定讀取的憑證才能登入，路徑請填寫絕對路徑。其他欄位說明可參考登入。

macOS 登入設定

  • 於範例程式資料夾開啟終端機畫面。

開啟終端機

語法執行範例程式：
- macOS 環境需輸入 Python 版本（python3）。
- 即可執行連線、登入、下單並收到即時回報資訊。
- 請確保所有元件與主程式（YSendOrder.py）位於同一目錄或指定路徑。

macOS 執行範例程式

  • 程式下單部分為 send_stock_order()，可更換股票代碼與下單股數。詳細內容可參考國內證券下單。

macOS 下單範例

  • 報價表部分為 ReadWatchListAll_api()，提供股票價格等當前資訊，可自行增加股票名單。詳細內容可參考報價表查詢。

macOS 報價表範例

四、備註

1. 可能出現的錯誤

  • 未安裝 .NET SDK。

未安裝 .NET SDK 錯誤

  • 安裝 .NET SDK 8 以下版本也會出現錯誤，建議更新至 8.0 以上版本。

.NET 版本過低錯誤

  • 此錯誤代表未安裝 pythonnet 套件，安裝方法可參考第三點第一項。

未安裝 pythonnet 錯誤

  • 此錯誤代表 Python 無法正確找到 .NET。可將 C:\Program Files\dotnet 資料夾刪除並重新安裝 .NET 8 以上版本。

無法找到 .NET 錯誤

  • 若仍無法解決，可於「編輯系統環境變數」中加入：DOTNET_ROOT=C:\Program Files\dotnet\。

環境變數步驟 1

  • 點擊環境變數

環境變數步驟 2

  • 新增系統變數

環境變數步驟 3

  • 加入 DOTNET_ROOT=C:\Program Files\dotnet\ 後，點擊確定並重新執行程式。

環境變數完成

2. 方法參數型別

Python 語言的數字型別為 int（整數）、float（浮點數）。故使用各項功能傳遞參數時，若非文件說明為浮點數型別，請以 int 型別傳遞。

例如現貨下單：

bool SendStockOrder(string, List<StockOrder>, enumLangType)

Field Name Description Type Size Memo
StockOrder 下單物件 Class
TradeKind 交易性質 short 00: 委託單；03: 改量；04: 取消；07: 改價
Price 委託價格 double 非限價請填 0

方法參數型別示意