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

2024年7月20日 15:55

少し前に立花証券e支店のAPIを検索してみました。
かなりプログラムに詳しいプロのエンジニアと思われる方の仕様や利用条件の解説がありました。

一方、初心者の方への解説がほとんどありませんでした。
初心者向けの解説が空白地帯になっています。

そこを補うために立花証券ｅ支店APIの「初歩の初歩」の解説をしてみます。
レベル的には「実用には使えない！」レベルです。
すみません。先に謝っておきます（笑

APIって何？

一般的な説明

分かったようで良く分からないAPI。
前職では、「APIって何？」と良く質問されました。

「プログラムでアクセスするインターフェースです。」
と答えていました。

質問した人はポカーンとした表情でした。
多分、期待した答えでは無かったのでしょう。

普通オンライン口座の操作は、PCやスマホでします。
ブラウザや専用アプリでログインして、パソコンだとマウスやキーボード、スマホだと指で操作し、情報を見たり、注文を出しています。

簡単に言うと、人間が目で画面を見て、手で動かして指示をしています。

APIは、プログラムでこの操作を行うためのインターフェースです。

「人間が目で画面を見て」の部分は、プログラムがサーバーからデータを受けて代替します。

もう少し詳しく言うと、プログラムでサーバーに欲しいデータを送るように指示を出し、プログラムでサーバーから返されるデータを受けます。

「手で動かして指示」の部分は、プログラムでサーバーに指示を意味するデータを送ることで代替します。

うーん、この説明も良く分からないですかね。
仕組みの説明だと直観的じゃないので、ストンと腑に落ちないですよね。

APIの利用メリットからの説明

APIの利用メリットを挙げると

・自動化したプログラムを用意すれば、人間がずっと画面を見て操作する必要がなくなる

・プログラムで動かすので、人間の操作より高速に操作できる

・証券会社が提供する画面以外の自分用にカスタマイズしたツールを作ることができる

などでしょうか。

「それがどうした！」という内容で、これも今一つ分かりにくいですね。

あからさまに言うと利用者の間口は狭いのです。
大半の方にはメリットが無いので、なるほど！と納得できないのでしょう。

こんな理由から、多くの方々から「API？、何それ？　チョコレート味？」という感じになっているのだと思います。

しかし世の中、捨てる神あれば、拾う神ありです。
メリットを感じられる一部の方には、強くアピールします。

実際には何をやっているの？

ああだ、こうだと余計な説明をしているより立花証券ｅ支店のAPIを実際に使って実験してみましょう。

ちなみに、APIが違えば全く違う仕組みなので、以下の手順の説明はｅ支店APIだけのものです。
この記事では、すみませんが一般的な知識は得られません。予め謝っておきます。

それでは、初歩の初歩の動きを見ていきましょう。
APIの動作を実感するため、ブラウザーを使い、手動でAPIを動かしてみます。

実際に以下の手動の実験をするためには、予め立花証券e支店に口座を開設しておいてください。

手動でログイン

まず最初にAPIサービスのページから「立花証券・ｅ支店・ＡＰＩ専用ページ」に行きます。

立花証券・ｅ支店・ＡＰＩ専用ページ」の「５．マニュアル」のページに行き
「１．共通説明」→「３．ブラウザからの利用方法」の
リンク「ｅ支店・ＡＰＩ、ブラウザからの利用方法」をクリックして、
Excelファイル「api_web_access.xlsx」をダウンロードしてください。

このファイルのシート「基本」に、手動でe支店APIにアクセスする方法の説明があります。

まずログインの部分です。

https://10.62.26.91/e_api_v4r5/auth/?{"p_no":"1","p_sd_date":"2020.11.07-13:46:35.000","sCLMID":"CLMAuthLoginRequest","sPassword":"********","sUserId":"********","sJsonOfmt":"5"}

これをコピーして必要な部分を修正して使います。

次に必要な修正点を説明していきます。

１．接続先
接続先が「10.62.26.91」と内部環境になっていますので、これを現在の接続先に変更します。

接続先は、
「立花証券・ｅ支店・ＡＰＩ専用ページ」の
「5.マニュアル」>「1.共通説明」>「1.ｅ支店・ＡＰＩ専用ＵＲＬ]
に書いてあります。

この記事を書いている時点では
https://kabuka.e-shiten.jp/e_api_v4r5/ （本番環境、最新バージョン）
https://demo-kabuka.e-shiten.jp/e_api_v4r5/ （デモ環境、最新バージョン）
となっています。

手動でテストのための接続ですから、APIの開発用のデモ環境が良いでしょう。
先程のエクセルに書いてあったURLの
「https://10.62.26.91/」
の部分を
「https://demo-kabuka.e-shiten.jp/e_api_v4r5/」
に書き換えます。

２．「auth/」
この部分はログインのときだけ入れます。

"sCLMID":"CLMAuthLoginRequest"
のときだけ、接続先と「?{」の間に「auth/」を入れます。

３．ユーザーID
次に伏字になっているユーザーIDの部分
「"sUserId":"********",」

を自身のユーザーIDに書き換えます。
「"sUserId":"hoge012345",」

４．パスワード
同じく伏字になっているパスワードの部分
「"sPassword":"********",」
を自分のパスワードに書き換えます。
「"sPassword":"fuga123abc",」

パスワードに、「#」「+」「/」「:」「=」の記号を使っている場合は、urlエンコーディングしてください。

具体的には
「APIへ入力したい記号」→「APIへの実際の入力」
「#」→「%23」
「+」→「%2B」
「/」→「%2F」
「:」→「%3A」
「=」→「%3D」
に置き換えてください。

例えば
a#b+c　→　a%23b%2Bc
と置き換えます。
何の工夫もなく、単に置き換えるだけです。
逆に工夫してしまうとエラーになります。

私は無駄に工夫して何回もエラーを出してしまいました。
・・・周りから、私の座右の銘は「人生、無駄な努力！」でしょうと言われています（笑

５．時刻
時刻の部分
「"p_sd_date":"2020.11.07-13:46:35.000",」
を現在時刻に置き換えます。
実は手動で実験するときは、これが一番面倒です。

手動の場合は、秒未満の小数点の以下の部分を「.000」としておいて問題ないです。

確かズレの許容は３０秒だったはずです。
ちょっと作業が遅れると、時刻エラーが返ってきます。

作成したURLをブラウザーのURL欄に貼り付けてから、時刻を修正し、Enterキーを押して実行すると良いです。

実際には、表計算で１～４の項目を入れ替えるワークシートを作っておくと便利です。

ブラウザーでAPIにログインしてみる

出来上がったurlのテキストをブラウザーのurl欄にコピーします。

コピーしたらurl欄にカーソルを置いたままエンターキーを押してください。
これでAPIに電文が投げられます。

デモ環境にログイン要求電文を送って返された電文。
電文と言っても、ブラウザーにテキスト画面が表示されるだけです。

これで分かるように、e支店APIがしていることは、クライアントがAPIに「url+テキスト」を送信すると、APIからテキストが返されてくるという単純な動作をしているだけです。
分かってみると、本当に単純な動作です。

手動でログアウトしてみる

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

１）接続先
ログインした後の接続先は、先ほどのログインで返された仮想urlを接続先として使います。

仮想URLは返されたデータの最後の方の４行です。
"sUrlRequest":
"sUrlMaster":
"sUrlPrice":
"sUrlEvent":
で始まっている各行の「:」の右側の""の中の文字列です。

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

逆にセッションが生きている間は、絶対公開しないでください。もし公開していまうと、セッションが切れるまでユーザーIDとパスワードを公開するのと同じになります。

セッションのライフタイムは、APIのQ&A「仮想URLの有効期限はいつまでですか？」にまとめたものがあります。

出す指示により仮想URLが異なり、ログアウトは"sUrlRequest"の値が接続先になります。

先ほどのログインで返された仮想urlの"sUrlRequest"の値は
https://demo-kabuka.e-shiten.jp/e_api_v4r5/request/NTk4MzI0MjEzMDYwNy0xMTYtNjMzMjk=/
でした。
このログインでの場合、これが次に実行するログアウトの接続先になります。
「大切な接続先＝トークンを公開して大丈夫？」と思われるかもしれませんが、このセッションは、とっくにライフタイムが終了しています（笑
公開しても全く問題ない状態です。

実際には自分で実行したログインで返された"sUrlRequest"の値を接続先の部分にセットしてください。

２．ログインではないので「auth/」は入れません。
接続先の後ろは「?{」です。

３．p_no
p_noは直前のrequestのp_noより必ず１以上インクリメントしてください。
不連続でもよいので、「直前のp_no」 < 「これから送るp_no」としてください。

例では、ログインがp_no:1なので、次に送るログアウトのp_noは２以上を指定します。

４．時刻
時刻はログインと同じく、ずれに注意してください
３０秒以上ずれるとエラーになるので、実行直前にブラウザーのURL欄で修正してください。

５．sCLMID
これは、コマンドを指定する部分です。
ログアウトは
"sCLMID":"CLMAuthLogoutRequest"
とセットします。

６．表示形式の指定
表示形式は、"sJsonOfmt"で指定します。
"sJsonOfmt":"5"
最初なので、"5"とセットしてください。

ブラウザーでAPIからログアウトしてみる

実行結果のサンプルです。

やはりブラウザーにテキストで返されます。

まとめ

このように立花証券e支店のAPIは、単なるテキストをHTTPS接続でやり取りしているだけです。

そして、APIを利用するプログラムは、上のようなテキストを切ったり貼ったりする手作業をプログラムで実行しているだけです。

HTTPS接続ができる言語やアプリであれば、テキストでAPIを使うことができます。
テキストをプログラムで扱ったことがあれば、e支店APIは簡単に利用できます。

この仕様のおかげで、例えばクラウド上でLinux + Python で完結させることも簡単です。
ちなみに設計開発を行ったエンジニアの方は、いかに使いやすくするかを相当考えたそうです。

立花証券e支店のAPIの構造は簡単だと思いますのでぜひ使ってみてください。

つづく・・・のか？？（笑

けっきょく立花証券ｅ支店のAPIの初歩の解説の
その2を書きました（笑

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