【ITニュース解説】Come scaricare fatture da SDI FatturaPA in C#

この解説では、C#というプログラミング言語を使って、イタリアの電子請求書システムであるSDI FatturaPAから請求書をダウンロードするシンプルなアプリケーションを作成する方法について説明する。このアプリケーションは、InvoicetronicというサービスのAPI（Application Programming Interface）を利用して、新しい請求書を取得し、ファイルとして保存する機能を持つ。

まず、このアプリケーションを作るための準備がいくつか必要となる。一つは、C#プログラムの作成と実行に必要なツール群である「.NET SDK」をパソコンにインストールすることだ。これは、C#のコードをコンピュータが理解できる形に変換したり、実行したりするために不可欠な道具となる。次に、Invoicetronic APIを利用するための「APIキー」を取得する必要がある。これは、Invoicetronicのサービスを使うための認証情報、いわばパスワードのようなもので、誰でも自由にサービスを使えるわけではないことを示している。最後に、実運用環境で請求書を扱う場合には、イタリアの歳入庁への登録が必要となるが、今回のチュートリアルではテスト環境を使うため、これは必須ではない。プログラムの作成には、多くのシステムで利用できる「dotnet」というコマンドラインツールと、「VS Code（Visual Studio Code）」というコードエディタを使用する。C#のプログラミングをVS Codeで快適に行うためには、「C# Dev Kit」という拡張機能のインストールと有効化が推奨されている。

アプリケーションの作成は、いくつかのステップに分かれる。最初のステップは、新しいC#プロジェクトを作成することだ。コマンドラインで「dotnet new console -n receive」と入力すると、「receive」という名前の新しいコンソールアプリケーションプロジェクトが作成される。コンソールアプリケーションとは、文字ベースで動作するシンプルなプログラムのことだ。プロジェクトが作成されたら、「cd receive」というコマンドで、作成されたプロジェクトのフォルダに移動する。

次に、このプロジェクトにInvoicetronicのSDK（Software Development Kit）を追加する。SDKとは、特定のサービスやプラットフォームと連携する際に、プログラマーがより簡単に開発できるように提供される便利なツールやライブラリのセットのことだ。コマンドラインで「dotnet add package Invoicetronic.Sdk」と入力すると、InvoicetronicのAPIと通信するための必要な部品がプロジェクトに追加される。SDKの追加が完了したら、「code .」と入力してVS Codeを現在のフォルダで開く。VS Codeでは、「Program.cs」というファイルがプロジェクトの主要なコードファイルとなる。

プロジェクトの作成とSDKのインストールが終わったら、次にSDKの設定を行う。Program.csファイルを開き、既存の内容を新しいコードで置き換える。このコードでは、まずInvoicetronic.Sdkライブラリから必要なクラス（Api、Client、Model）を読み込んでいる。そして、「Configuration」というクラスのインスタンス（設定を保持するオブジェクト）を作成し、APIに接続するための情報を設定する。設定する情報のうち、「BasePath」には、APIのアクセス先となるURL（https://api.invoicetronic.com/v1）を指定する。これは、どのサーバーに請求書の情報を要求するかをAPIに伝えるための住所のようなものだ。「Username」には、取得済みのAPIキーを設定する。ここで設定するのは、開発用の「テストキー」である。APIキーは通常、テスト用と本番用の2種類があり、テストキーは「ik_test_」で始まる。本番用のシステムに接続する際は、本番用のAPIキーを使用するが、チュートリアルではテストキーで十分だ。

SDKの設定が完了すると、いよいよ請求書をダウンロードする処理を記述する。追加するコードでは、まず「ReceiveApi」というクラスのインスタンスを、先ほど設定したconfig（設定情報）を使って作成する。ReceiveApiは、請求書を受け取るためのAPIとやり取りする役割を担う。そして、「receiveApi.ReceiveGetAsync」というメソッドを呼び出す。このメソッドは、実際にAPIサーバーに請求書の取得を要求する処理を実行する。メソッドの引数として「unread:true」と指定することで、まだ読み込んでいない（新しい）請求書だけを取得するようにAPIに指示する。また、「includePayload:true」と指定することで、請求書のメタデータ（誰からの請求か、ファイル名など）だけでなく、請求書の中身そのものも一緒に取得するように指示する。もしこの引数を指定しないと、請求書の中身は取得されず、メタデータのみが返される。この処理は、APIとの通信を伴うため時間がかかる可能性があるため、「await」キーワードを使って非同期に実行される。これにより、請求書が取得されるまでプログラムが他の処理をブロックせず、効率的に動作する。

請求書がAPIから正常に取得されると、それらは「inboundInvoices」という変数にリストとして格納される。プログラムは、取得された請求書の数をコンソールに表示し、その後、それぞれの請求書に対してループ処理を実行する。ループの中では、各請求書の「Encoding」プロパティをチェックする。Encodingは、請求書のデータ形式がXML形式か、それともBase64という形式でエンコード（符号化）されているかを示す。XML形式の場合、「File.WriteAllText」メソッドを使って、請求書の内容（Payloadプロパティに格納されている）をテキストファイルとして保存する。ファイル名は、請求書の「FileName」プロパティから取得する。Base64形式の場合、まず「Convert.FromBase64String」メソッドでBase64形式のデータを元のバイナリデータに戻し、その後「File.WriteAllBytes」メソッドを使ってバイナリファイルとして保存する。各請求書の保存が完了すると、どのファイルがどのサプライヤー（請求元）からダウンロードされたかをコンソールに表示する。

APIとの通信中には、ネットワークの問題やAPIキーの誤りなど、さまざまなエラーが発生する可能性がある。このような場合にプログラムが予期せず終了しないように、請求書ダウンロードの処理全体は「try-catch」ブロックで囲まれている。tryブロック内のコードでエラー（ApiException）が発生した場合、プログラムはcatchブロックに処理を移し、エラーメッセージとエラーコードをコンソールに表示する。これにより、何らかの問題が発生した際にも、その原因を特定しやすくなる。

すべてのコードを記述したら、コマンドラインに戻り、「dotnet run」と入力してアプリケーションを実行する。正常に動作すれば、「Ricevute N fatture」（Nは取得した請求書の数）というメッセージが表示され、その後、ダウンロードされた各請求書のファイル名とサプライヤーの情報が表示される。ダウンロードされた請求書ファイルは、アプリケーションが実行されたフォルダに保存されている。もし2回目以降に実行した場合、unread:trueが指定されているため、新しい請求書が到着していない限り、ほとんど請求書がダウンロードされない可能性がある。

この一連の作業を通じて、私たちはいくつかの重要なことを学んだ。まず、Invoicetronic SDKを使用する際には、APIの接続先を示すBasePathと、認証情報であるAPIキー（ここではUsernameとして設定）をConfigurationクラスに設定する必要があること。次に、特定のAPIエンドポイント（この場合は請求書の受信）とやり取りするために、「ReceiveApi」のような対応するクラスのインスタンスを作成すること。そして、そのインスタンスが持つメソッド（「ReceiveGetAsync」など）を呼び出すことで、実際にAPIからデータを取得できること。また、新しい未読の請求書のみを取得したい場合はunread:trueを、請求書の実際のコンテンツを含めて取得したい場合はincludePayload:trueを引数として渡すことを理解した。さらに、取得した請求書データは、「Receive」クラスのインスタンスとして返され、そのプロパティ（Encoding、FileName、Payloadなど）を使って、請求書の形式を判断したり、ファイル名を取得したり、請求書のコンテンツを読み取ったりできることも確認した。Payloadには生のテキストデータかBase64エンコードされたデータが含まれるため、Encodingプロパティに応じて適切にデコードする必要があるのだ。