国税庁インボイスシステムを使ってみた：i-CrossAPI編

前回はMicrosoftが提供するRPAツールPower Automate Desktopを使って国税庁の適格請求書発行事業者公表システムWeb-API（以下インボイスシステム）を使ってみました。

今回はIBMiで簡単にREST APIの活用が可能なi-Cross API(アイ、クロス、エーピーアイ)を使ってみました。

インボイスシステムに関して

インボイスシステム概要に関しては前回のコチラか、本家の国税庁サイトのコチラを参照お願いいたします。詳細な仕様に関しては国税庁サイトから入手可能なPDFファイル「適格請求書発行事業者公表システムWeb-API機能のリクエストの設定方法及び提供データの内容について」の参照をお願いいたします。

i-Cross APIを使う理由

i-Cross APIはIBMiにREST APIを設定し、外部システムからコールされるとjson形式で情報提供する①サーバー機能、逆に外部システムが提供しているREST APIをIBMiがコールし受け取ったjson形式のデータをIBMiライブラリーの物理ファイルへ自動変換し直接ダウンロードする②クライアント機能が使えます。

今回の場合REST APIを提供している外部システムが国税庁となり、i-Cross APIのクライアント機能を使う事になります。

このクライアント機能で嬉しいのは外部システムから取得したjson形式のデータを自動で物理ファイル化する事です。ですのでIBMiと外部システムとの連携の場合、必要とされていた連携用のシステム（例えば前回例のようなRPAとRPA自身が稼働するH/W、監視、保守・・）が不要となりIBMi内で完結し、これまでのIBMiスキルを継承しクラウドに代表する最新のSaaSシステムが提供する機能やデータをREST APIを経由してIBMi自体で活用が可能です。

i-Cross API設定

今回も前回同様「取得期間を指定して情報を取得する機能」を下記のようなURLで試してみました。これらURLをi-Cross APIに設定します。

https://web-api.invoice-kohyo.nta.go.jp/1/diff?id=アプリケーションID&from=2023-05-10&to=2023-05-11&type=21

i-Cross APIをIBMiに導入後、エミュレーター画面から「APIBRIDGE」コマンドで下図のような設定メニューを表示しF6キーを押し定義を新規追加をします。

下図、「定義KEY」と「定義名」は任意の値で設定します。「API実行URL」と「メソッド」は、今回試用する「取得期間を指定して情報を取得する機能」の仕様に従って「https://web-api.invoice-kohyo.nta.go.jp/1/diff」と「*GET」を指定します。

次にURL後ろのクエリパラメータである「id=アプリケーションID&from=2023-05-10&to=2023-05-11&type=21」を指定するためEnterキーを押します。すると上図では「パラメータ：HEADERS 1」だった箇所が、下図では「パラメータ：BODY 1」に変わります。

数回Enterキーを押し、下図のようにQUERYパラメーター指定画面を表示します。まずは「id=アプリケーションID&from=2023-05-10&to=2023-05-11&type=21」の「id=アプリケーションID」を「パラメータ：QUERY 1」に指定します。「キー」はid、「値」は国税庁に申請したアプリケーションIDを指定します。

次に「id=アプリケーションID&from=2023-05-10&to=2023-05-11&type=21」の「from=2023-05-10」を指定するため次ページキーを押します。すると「パラメータ：QUERY 2」となり、追加のパラメータ指定が可能となります。「キー」はfrom、「値」は2023-05-10を指定します。

「id=アプリケーションID&from=2023-05-10&to=2023-05-11&type=21」の「to=2023-05-11」を指定するため上記同様に次ページキーを押し「パラメータ：QUERY 3」として追加します。「キー」はto、「値」は2023-05-11を指定します。

最後に「type=21」を指定するため次ページキーを押し「パラメータ：QUERY 4」として追加します。「キー」はtype、「値」は21を指定します。

このようにEnterキーでheader、body、cookie、queryなど目的に合ったパラメータを選択し、次ページキーで、それぞれ10個までパラメータの指定が可能です。

Enterキーを押し、今回指定が不要の他パラメーター設定画面をスキップして進むと、取得したデータの保存先ライブラリーやレスポンス/リクエストヘッダーを記録するか否かを指定する下図画面が表示されます。F5キーで保存します。

下図のような実行と保存確認画面が表示されますので、再度F5キーを押します。

定義したINVOICEが「定義KEY」として保存され、APIのコールが完了します。

jsonデータを自動で物理ファイル化

IBMiが受け取ったjsonデータは下記です。announcementに入っている0,1,2・・・・の内容が欲しいデータである事が分かります。

i-Cross APIは受け取ったjsonデータを自動で物理ファイル化します。指定した保存先ライブラリーを参照すると以下のように「ROOT」と「ROOT_00001」が作成されています。

下図は「ROOT」内容です。

下図のようにjsonデータと対比させると自動作成された「ROOT」ファイルのカラム名とその値の関係が理解できると思います。

下図は「ROOT_00001」内容です。jsonデータと対比させると「ROOT_00001」のカラム名はjsonデータのannouncementに入っている0,1,2・・・・内のキー名が対応している事が分かります。

この「ROOT_00001」ファイルの一番右を参照するとカラムがpopularName_previousNmaeで終わらずjsonファイルにはない「root」が追加されています。カラム「root」の値はannouncement0～連番である事が分かります。

今回は「ROOT_00001」さえ入手できれば良さそうですが、下図のように「ROOT」ファイルのカラムannouncement値と「ROOT_00001」ファイルのカラムroot値をjoinさせるとjsonデータの階層ごとに分かれたファイルを1枚の表のようにする事も可能な作りになっています

コマンド実行

設定した定義をコマンド実行するには下記のようなAPIBRIDGEコマンドを用います。

APIBRIDGE EXEC(*EXEC) KEY(INVOICE) QRKEY(id from to type) QRVALUE('アプリケーションID' '2023-05-10' '2023-05-11' '21')

例では期間指定であるfrom,toを決め打ちで'2023-05-10'と'2023-05-11'にしましたが、「適格請求書発行事業者公表システムWeb-API機能のリクエストの設定方法及び提供データの内容について」記載の他パラメータを含めて、実運用では変数にする事で目的に合った設定が可能です。

divide(分割数)に関して

今回例に用いた「取得期間を指定して情報を取得する機能」は国税庁側の仕様で全件データを一発で取得することはできません。応答データが500件を超えるとIBMi側(i-Cross APIクライアント機能)で下記のように明示的にdivideパラメータを2、3、4、5、6、7、8・・・・のように指定し、数回に分けてリクエストする必要があります。

APIBRIDGE EXEC(*EXEC) KEY(INVOICE) QRKEY(id from to type divide) QRVALUE('アプリケーションID' '2023-05-10' '2023-05-11' '21' '2')

ですので実運用ではjsonデータ内のdivideSizeを最初に参照して(今回例では21分割)、divideSize数リクエストを繰り返し、インボイスシステムへ要求する事になります。

終わりに

「APIで連携」と言うと、過去にはシステムを構成する「何か」をメンテナンスすると、すぐに使えなくある時代がありました。ですのでH/W機器、OS、データベース、ミドルエア、プログラム言語など多様な要素の組み合わせを強く意識する必要がありました。Web-APIの世界になってREST APIが「連携の共通の仕組み」として使えるようになった昨今、URLだけを意識すればよく、その先のシステムを全く意識する必要が無くなりました。

REST APIをサポートするシステムはモダンなSaaSアプリケーションだけではありません。REST APIはEXCELやハンディターミナルのような機器でもサポートしています。乱暴な言い方をすると、気の利いたシステムは「連携の共通の仕組み」を使えるようにREST APIをサポートしています。i-Cross APIはこれら「気の利いたシステム」とIBMiを柔軟に連携する事を支援いたします。

ソリューション・サービス

クラウド・サービス

IBM i 関連

ブログ