はじめての立花証券e支店API　その２

2024年8月14日 08:55

今年も草刈りに邁進しています。
木も少しずつ切り倒しています。
目指せ、シャルドネ畑ｗ

草刈りをしていて実感するのは、小型ファンが付いた送風ジャケットの凄さ。
ファンを回し、スポーツドリンクをきちんと飲めば、８月の炎天下に作業できてしまいます。驚きです！
暑さを理由にサボれないのは、困ったものですが・・・ｗ

株式会社空調服さんが上場されたら全力で買っちゃいそうですｗ

前回の記事「はじめての立花証券e支店API」的な解説

では、「APIってなに？」という簡単な解説と、手動で立花証券ｅ支店のAPIを動かしてみました。

今回はその続きです。

「APIってなに？」という問いに対しては、実は簡単で明解な答えが有ります。

APIには、できることに全て仕様書がある

立花証券e支店の場合、手動の実験で確認したように、APIも普通のWeb画面と同じ様にブラウザーで応答を表示できました。

APIはテキストの文字列。
普通のWeb画面の場合は、htmlで記述されたテキストデータです。
どちらもテキストデータということは同じです。

一番の違いは、仕様書が利用者に公開されているかどうかです。

APIは仕様書が公表されて運営されます。機能の変更は、仕様書の変更が伴います。

普通のWeb画面の場合、通常は仕様書が公開されません。
もし仕様書が公開されれば、普通のWeb画面でもある程度APIとして利用できるかもしれません。

軽いデータ、扱いやすい形式

２つ目は、軽いデータ、プログラムで扱い易いデータ形式です。
APIは、人間が画面を見たり、マウスで操作したりすることを考えていないので、データをシンプルに軽くしてあります。

またデータの形式も、プログラムで扱い易い形式です。
ｅ支店の場合は、JSONというデータフォーマットです。色々な言語でライブラリが用意されていて、プログラムで扱い易いデータフォーマットです。
解説もたくさんありますので調べてみてください。

必要条件と、十分条件。
他にも細かい論点が有るとは思いますが、大きくはこの２点でしょうか。

直観的ではないかもしれませんが、この2つの基準がAPIの特徴を表しています。

ここから下は立花証券e支店のAPIの電文の作り方になります。
一般的な話は一つもありませんので、先に謝っておきます。

立花証券ｅ支店APIの仕様書

APIには必ず有る仕様書、立花証券ｅ支店のAPIの場合はどうなっているか見てみましょう。

リンク「立花証券・ｅ支店・ＡＰＩ専用ページ」に飛んだ先の「５．マニュアル」に仕様書があります。色々なマニュアルが有ります。

分からないマニュアルは放っておきましょう

サンプルプログラムを作り始めるときに、私も読んでみました。
正直にいうと、初めはさっぱり分からないものばかりでした。

それから少しずつ必要なところを調べ、仕様書を読んできました。
それでも未だに全く分からないマニュアルも有ります（笑

サンプルプログラムを作っただけの少ない経験ですが、全部の仕様書を読まなくても大丈夫です。

取り敢えず市場に注文を出したり、口座の状況を把握するのに必要な仕様書だけを抑えれば、後は知りたくなった時に読めば大丈夫です。

例えば最初に出てくるマニュアル「立花証券・ｅ支店・ＡＰＩ、インタフェース概要」です。

皆さん、これを開いて「分からない！」と頭を抱えます。
私がそうでした（笑

APIを手動で動かしてみて、データがテキストで返ってくるのを確認した方は、
2ページの「インターフェース概念図」の仮想URLと
3〜4ページの各機能のマニュアル
をざっと眺めておくだけで良いです。

「2ページの「インターフェース概念図」の仮想URL」は、下に解説を書きましたので、そちらで代替できます。

その他は後回しで大丈夫です。
必要になるまで放っておきましょう！

特に「シーケンス図」は、手動で確認した事実を、プロのエンジニア向けに書いてあるだけです。
書いたプログラムが正しく動けば良い人は、放って置いてください（笑

e支店APIへの基本の電文形式

APIへの電文は、
ログインだけ、［auth/］が入り
［接続先URL］＋［auth/］＋［?］＋［データ部分］
になります。

ログイン後のコマンドは、
［ログインで返された仮想URL］＋［?］＋［データ部分］
の形式になります。

ログインした後の電文は、ログインで返された各データ項目を利用して電文を作ります。

この電文の構成は、立花証券e支店のAPIの「お約束」ということで丸覚えでお願いします。
もう「こんなもの」とご認識ください。

ちなみに［ログインで返された仮想URL］は、ログインで確立されたセッションでの、いわゆるトークンになります。ライフタイムはそのセッションの間だけです。ログアウトしてしまえば、もう使えません。

因みにログインの［接続先URL］は、これを書いている時点では
５．マニュアル
１．共通説明
ｅ支店・ＡＰＩ専用ＵＲＬ
https://kabuka.e-shiten.jp/e_api_v4r5/ （本番環境、最新バージョン）
https://demo-kabuka.e-shiten.jp/e_api_v4r5/ （デモ環境、最新バージョン）
になります。

認証機能は上に書いたように
［接続先URL］＋［auth/］＋［?］＋［データ部分］
です。
他の機能は［ログインで返された仮想URL］を使います。

ログインで返された仮想URLと各機能の関係は次のようになります。
各項目は「５．マニュアル」のページの左側メニューです。

「３．業務機能（REQUEST I/F）」の項目は
["sUrlRequest"の値]＋［?］＋［データ部分］
です。

「４．マスタ機能（REQUEST I/F）」の項目は、
["sUrlMaster"の値]＋［?］＋［データ部分］
です。
追加でニュースの取得も同じ"sUrlMaster"仮想URLになります。

「５．時価情報機能（REQUEST I/F）」の項目は
["sUrlPrice"の値]＋［?］＋［データ部分］
です。

「６．注文約定通知（EVENT I/F）」の項目は
["sUrlEvent"の値]＋［?］＋［データ部分］
です。
この機能は注文約定通知だけでなく、プッシュ型のリアルタイム株価やニュースも取得できます。

リアルタイムにプッシュ型で、約定通知や株価、ニュースが配信されるのは個人の投資家には大きなメリットだと思います。

一方、プッシュ型のデータは、負荷を考えたリアルタイム系の処理が必要なので、なかなか手強いです。
私の腕前では全く手に負えませんでした（笑

基本のデータ仕様

データ形式が分かったら、次に見ていくマニュアルは、APIに何を送れば良いかの基本項目が書いてある
５．マニュアル > １．共通説明 > ４．共通項目、認証機能
の
「立花証券・ｅ支店・ＡＰＩ（ｖ４ｒ５）、REQUEST I/F、利用方法、データ仕様」
です。

この仕様書の中の
「２．利用方法」の
「（１）共通項目」の要求に「設定」と表示された項目を電文にjson形式でセットしてAPIに送ります。

具体的には、
p_no
p_sd_date
sCLMID
の３項目です。

追加で表示制御のために
sJsonOfmt
もセットできます。
最初は「5」でセットしてください。

合計４項目です。

手動で実験したログアウトの送信電文がこの項目と一致します。
改行とインデントを入れると、データ部分は次のようになります。

{
	"p_no":"2",
	"p_sd_date":"2024.07.07-11:49:36.000",
	"sCLMID":"CLMAuthLogoutRequest",
	"sJsonOfmt":"5"
}

コマンド電文の書き方

次に見ていくのは
ＡＰＩ専用ページ > ５．マニュアル
のページの左メニュー
「３．業務機能（REQUEST I/F）」
です。

通常のコマンドの仕様書で、基本動作のコマンドの解説です。
データ項目が少ない「７．買余力」を例に見ていきましょう

１．要求
{
 "sCLMID":"CLMZanKaiKanougaku",
 "sIssueCode":"",
 "sSizyouC":""
}

sCLMID	機能ＩＤ	CLMZanKaiKanougaku
sIssueCode	銘柄コード	未使用
sSizyouC	市場	未使用

【注意】
　要求項目の銘柄コード、市場は不要です。
　ただし応答項目は影響を考慮し残してあります。

となっています。

この仕様書の「１．要求」に書いてある項目をAPIに送信すればAPIが動作します。

「７．買余力」の場合、３つの項目のうち
「sIssueCode 銘柄コード未使用」
「sSizyouC 市場未使用」
の２項目は、未使用となっているので不要です。

必要なのは
「sCLMID 機能ＩＤ CLMZanKaiKanougaku」
だけです。

設定する項目は、上に書いたように
［ログインで返された仮想URL］＋［?］＋［データ部分］
です。

まず［ログインで返された仮想URL］です。
ログインで返された仮想URLは、そのセッション限りのトークンになるのでログイン毎に異なります。
ログインの応答電文の各項目を保存し、使います。

「７．買余力」は、「３．業務機能（REQUEST I/F）」の中の機能なので、
ログインで返されたsUrlRequestの仮想URLをセットします。

次は"?"です。

その後ろは［データ部分］の
p_no
p_sd_date
sCLMID
sJsonOfmt
になります。

書き方は、json形式で

{
	"p_no":"2",
	"p_sd_date":"2024.07.07-11:49:36.000",
	"sCLMID":"CLMZanKaiKanougaku",
	"sJsonOfmt":"5"
}

になります。

ログアウトとの違いは、"sCLMID"の「:」より後ろの部分を
"CLMZanKaiKanougaku"
にするだけです。

全部繋げると

https://demo-kabuka.e-shiten.jp/e_api_v4r5/request/NTk4*************MzMjk=/?
{
	"p_no":"2",
	"p_sd_date":"2024.07.07-11:49:36.000",
	"sCLMID":"CLMZanKaiKanougaku",
	"sJsonOfmt":"5"
}

あとはhttpsで立花証券e支店のAPIに投げるだけ。

要求項目が複数ある場合

次に「１０．注文一覧」のように要求項目（送信項目）が複数ある場合です。

仕様書は次のようになっており、要求項目が４個あります。

１．要求
{
 "sCLMID":"CLMOrderList",
＊＊＊＊以下は任意指定項目、指定項目をＡＮＤ条件で検索＊＊＊＊
 "sIssueCode":"8411",
 "sSikkouDay":"",
 "sOrderSyoukaiStatus":""
}


sCLMID		機能ＩＤ	CLMOrderList

sIssueCode	銘柄コード	指定あり：指定１銘柄のリスト取得（例:"8411"）
				指定なし：全保有銘柄のリスト取得（例:""）


sSikkouDay	注文執行予定日（営業日）	
				CLMKabuNewOrder.sEigyouDay 参照
				指定あり：指定１営業日のリスト取得（例:"20231018"）
				指定なし：全保有営業日のリスト取得（例:""）

sOrderSyoukaiStatus
		注文照会状態
				""：指定なし
				1：未約定
				2：全部約定
				3：一部約定
				4：訂正取消(可能な注文）
				5：未約定+一部約定
				指定あり：指定１状態のリスト取得（例:"2"）
				指定なし：全保有状態のリスト取得（例:""）

【注意】
　要求項目（sCLMID 以外）は任意指定（ＡＮＤ条件）項目で、
　指定項目値該当情報をリストとして応答する。
　注文執行予定日（営業日）は夕方の日替処理（で翌営業日に変更）以降、
　その前後（繰越前、繰越後）の情報取得に使用する。
　過去の注文情報が取得できる訳ではないので注意されたい。

複数ある項目は、例にあるように、sCLMIDの後に各項目を繋げていきます。
因みにjson形式は順番は関係なかったはずなので、全部の項目を繋げれば大丈夫だったはずです。

https://demo-kabuka.e-shiten.jp/e_api_v4r5/request/NTk4*************MzMjk=/?
{
	"p_no":"3",
	"p_sd_date":"2024.07.07-11:50:36.000",
	"sCLMID":"CLMOrderList",
	 "sIssueCode":"",
 	"sSikkouDay":"",
 	"sOrderSyoukaiStatus":"",
	"sJsonOfmt":"5"
}

json形式は、最後の項目は後ろに「,」が無く、「}」で終わります。
この処理が、プログラムでは地味に面倒です（笑

作った電文の投げ方

作った電文（テキスト）を str_url とすると、
pythonの場合だと

# APIに接続
http = urllib3.PoolManager()
req = http.request('GET', str_url)

になります。req で応答電文を取り出せます。

たったこれだけ。
ビックリするほど簡単です。

１．認証機能（認証I/F）
３．業務機能（REQUEST I/F）
４．マスタ機能（REQUEST I/F）
５．時価情報機能（REQUEST I/F）
は、すべてこれでOK！

６．注文約定通知（EVENT I/F）
だけは少し違いますので、githubの
e_api_event_receive.py
（https://github.com/e-shiten-jp/e_api_event_receive.py）
542 - 546 行目
ストリーム形式で接続の部分を見てください。

Excel VBAの場合は
Excel_order_correct_cancel_price.xlsm
のAPIへの接続「Public Function GetPage(work_url As String) As String」を参照ください。

その他の言語の場合は、J-QuantsAPIのExcel化の記事
J-Quants API への接続をChatGPTに聞いてExcel VBAに書き直してみた
のようにChatGPTなどのAIにpythonの接続部分を入れて聞いてみてください。
きっと簡単に接続できます！？（笑

立花証券e支店のAPIへの要求電文作成のまとめ

仕様書
すべての仕様書を理解する必要はないです。

電文の書式
ログイン：
［接続先URL］＋［auth/］＋［?］＋［データ部分］

ログイン後のコマンド：
［ログインで返された仮想URL］＋［?］＋［データ部分］

複数項目の電文
json形式で繋げて書いていくだけです。

上でみたように、立花証券e支店のAPIは、利用するプログラム言語に
https接続メソッド
jsonのライブラリ
が有れば簡単に利用できます。
テキストを簡単に扱える言語ならば更に良いです。

最後に

立花証券e支店のAPIは、
・株取引については、ある程度分かるけど
・プログラムでテキストの処理ならば、ある程度できるけど
という方を対象に作られています。

webやhtmlの知識は、APIへの接続でほんの少し必要ですが、詳しい必要はありません。
私がそうなのですが、株のAPIの利用は、株取引をしたいからで、webの仕組みに詳しくなりたいためでは無いです（笑

世の中のAPIのように、web技術のハードルを上げていないので、ぜひ試してみてください。

その３　「落とし穴編？」も書いてみました（笑

はじめての立花証券e支店API その２