【ITニュース解説】How to download SDI FatturaPA invoices with C#

このニュース記事は、C#というプログラミング言語を使って、イタリアの電子請求書システム「SDI FatturaPA」から請求書をダウンロードする実践的な方法を解説している。具体的には、InvoicetronicというオンラインサービスのAPI（アプリケーション・プログラミング・インターフェース）を利用し、受信した請求書を自動的に取得するコンソールアプリケーションの作成手順を学ぶことができる。システムエンジニアを目指す初心者にとって、外部サービスとプログラムを連携させる基本的な流れを理解する良い出発点となるだろう。

プログラムを作成する前に、いくつかの準備が必要となる。まず、C#プログラムを開発し実行するための基盤となる「.NET SDK」を自分のパソコンにインストールする必要がある。次に、Invoicetronicサービスにアクセスするための「APIキー」を取得しなければならない。これは、プログラムがサービスに接続する際の認証情報、いわば「鍵」のようなもので、このキーがなければサービスの利用は許可されない。そして、もしこのシステムを実際に運用環境で利用する場合には、イタリアの税務署に登録する必要がある。今回のチュートリアルでは、テスト環境を使用するため、この登録はすぐに必要ではないが、将来的な運用を考えると重要な前提条件となる。開発ツールとしては、コマンドラインから操作する「dotnet tool」と、多機能なテキストエディタである「VS Code」が推奨されているが、Visual StudioやRiderといった他の開発環境を使っても問題ない。VS Codeを利用する場合には、「C# Dev Kit」という拡張機能をインストールすると、C#開発がより快適になる。

準備が整ったら、プログラムの作成を開始する。最初のステップとして、新しいC#のコンソールアプリケーションプロジェクトを作成する。コマンドプロンプトやターミナルで「dotnet new console -n receive」というコマンドを実行すると、「receive」という名前の新しいフォルダが作成され、その中にC#プロジェクトの基本的なファイル一式が自動的に生成される。「console」は文字ベースのシンプルなアプリケーションを意味し、「-n receive」はプロジェクト名を指定するオプションである。プロジェクトフォルダが作成されたら、「cd receive」コマンドでそのフォルダに移動する。

次に、Invoicetronicのサービスと連携するために必要な「SDK（Software Development Kit）」をプロジェクトに追加する。SDKは、特定のサービスを利用するための便利な機能やライブラリがまとめられたもので、これを導入することで、複雑な通信処理などを自分で記述する手間を省くことができる。SDKを追加するには、プロジェクトフォルダ内で「dotnet add package Invoicetronic.Sdk」というコマンドを実行する。これにより、Invoicetronicとの連携に必要な部品がプロジェクトに組み込まれる。SDKの追加が完了したら、「code .」コマンドでVS Codeを起動し、現在のプロジェクトフォルダを開き、Program.csファイルをクリックして編集画面に表示させる。

SDKがインストールされたら、そのSDKを設定する必要がある。Program.csファイルの内容を、APIへのアクセス先と認証情報を指定するように書き換える。具体的には、Configurationというクラスのインスタンスを作成し、BasePathプロパティにInvoicetronic APIのURLを、Usernameプロパティに取得済みのAPIキーを設定する。APIキーには「テスト用」と「本番用」の二種類があり、テスト用は「ik_test_」で始まり、本番用は「ik_live_」で始まる。このチュートリアルでは、実際の運用に影響を与えないテスト環境を使用するため、必ず「ik_test_」で始まるテスト用のAPIキーを設定する。この設定により、プログラムがどのAPIサービスに、どの認証情報を使ってアクセスするかが決まる。

設定が完了すると、いよいよAPIを通じて請求書をダウンロードするリクエストを作成する段階である。設定情報（config）を使ってReceiveApiというクラスのインスタンスを作成する。このReceiveApiは、請求書を受信する（受け取る）ための機能を提供するもので、これを介してAPIと通信する。実際に請求書データを取得するには、receiveApi.ReceiveGetAsync()メソッドを呼び出す。このメソッドにはいくつかのオプションを指定でき、ここではunread:trueとincludePayload:trueを指定している。unread:trueは、まだプログラムで処理していない（未読の）請求書のみを取得するという意味である。includePayload:trueは、請求書の「中身」（実際のデータ）も一緒に取得するという指定である。この指定がない場合、請求書のメタデータ（送信元や日付など）は取得できるが、ファイルの内容は含まれない。今回は請求書の中身をダウンロードしたいのでtrueを設定する。

APIから取得した請求書データはinboundInvoicesというリスト変数に格納される。プログラムは、取得できた請求書の数を表示した後、リスト内の各請求書に対して処理を行う。各請求書オブジェクトは、Encoding（データ形式）、FileName（ファイル名）、Payload（請求書の中身）といったプロパティを持っている。Encodingプロパティで、PayloadがXML形式なのか、それともBase64という形式でエンコードされているのかを判断し、それぞれに応じた方法でファイルを保存する。XML形式であればそのままテキストファイルとして保存し、Base64形式であればデコード（元の形式に戻す）してからバイナリファイルとして保存する。FileNameプロパティの値を使って適切なファイル名を付ける。ダウンロードが完了したら、どのベンダーからどのファイル名で請求書をダウンロードしたかをコンソールに表示する。もしAPIとの通信中にエラーが発生した場合は、try-catchブロックによってエラーを捕捉し、エラーメッセージとエラーコードを表示するように記述されている。これは、プログラムが問題に直面した際に、その原因を特定するのに役立つ。

これらのコードを記述したら、ターミナルに戻り「dotnet run」コマンドを実行する。このコマンドは、作成したC#プログラムをコンパイルし、実行する。プログラムが正常に動作すれば、「Received X invoices」のようなメッセージと、ダウンロードされた請求書のファイル名やVAT ID（付加価値税ID）がコンソールに表示されるはずである。ダウンロードされた請求書ファイルは、現在のプロジェクトディレクトリ内に保存されているため、ファイルエクスプローラーなどで内容を確認できる。

このチュートリアルを通して、外部APIとの連携における重要なステップを学ぶことができた。具体的には、APIのベースパスや認証情報（APIキー）を適切に設定する方法、目的の機能を提供するAPIクラス（ReceiveApi）をインスタンス化する方法、そしてそのクラスのメソッド（ReceiveGetAsync）を呼び出してデータを取得する方法である。さらに、unreadやincludePayloadといった引数を使って、取得するデータの種類や条件を制御できること、そしてAPIから返されるデータがEncodingやPayloadといったプロパティによって構成されており、それぞれのデータ形式に応じて適切に処理する必要があることを理解できた。これらの知識は、将来的に他のAPIサービスと連携するプログラムを開発する際にも役立つ、システムエンジニアにとっての基本的なスキルとなるだろう。