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

システムエンジニアを目指す皆さんにとって、現代のビジネスにおいて「電子請求書」は避けて通れないテーマの一つである。今回の記事は、プログラミング言語であるC#を使って、イタリアの電子請求システム「SDI FatturaPA」に請求書を送る方法を解説している。この一連の作業は、外部サービスと連携してシステムを構築する際の基本的な流れを学ぶ良い機会となるだろう。

まず、「SDI FatturaPA」とは何かについて説明しよう。これはイタリアで企業が電子的に請求書をやり取りするための国のシステムである。日本でも「インボイス制度」が導入されたように、各国で電子的な商取引を推進する動きが進んでおり、SDI FatturaPAはそのイタリア版と理解すれば良い。企業は請求書を特定のXML形式という、コンピューターが扱いやすいデータ形式で作成し、SDIという国のシステムを通じて送信・受信する。これにより、請求書の処理が効率化され、税務当局も取引内容を把握しやすくなるというメリットがある。

しかし、このSDI FatturaPAに直接接続して請求書を送るには、多くの専門知識と複雑な手順が必要となる。そこで利用するのが「Invoicetronic API」という外部サービスだ。APIとは「Application Programming Interface」の略で、異なるソフトウェアやサービス同士が情報をやり取りするための窓口や規約のようなものだと考えると良い。Invoicetronic APIは、SDI FatturaPAへの接続、データの変換、認証といった複雑な部分をInvoicetronic社が代行してくれるサービスである。これにより、私たちはSDIの複雑な仕組みを直接知らなくても、Invoicetronic APIを介して簡単に電子請求書を送れるようになる。

今回の開発で使うプログラミング言語はC#だ。C#はマイクロソフトが開発した言語で、WindowsのアプリケーションやWebサービス、ゲーム開発など、幅広い分野で利用されている。そして、Invoicetronic APIをC#から簡単に利用するために、「Invoicetronic SDK」というものが提供されている。SDKとは「Software Development Kit」の略で、特定のサービスやプラットフォームと連携するためのプログラム部品のセットである。SDKを使うことで、APIにデータを送るための通信処理や、APIからの応答を解釈する処理などを、一から自分で書く必要がなくなる。SDKが用意してくれている関数やクラスを呼び出すだけで、簡単にAPIの機能を利用できるのだ。

開発を進めるには、いくつかの準備が必要となる。まず、C#プログラムを実行するための「.NET SDK」がコンピューターにインストールされていること。これはC#開発の土台となるツール群だ。次に、APIを利用するための「APIキー」を取得すること。APIキーは、私たちがInvoicetronic APIを利用する際の「鍵」のようなもので、この鍵を提示することで、API側は「この利用者は正当なユーザーだ」と認識し、サービスへのアクセスを許可する。テスト用のキーと本番用のキーがあり、開発中は安全のためにテスト用のキーを使って機能を試すのが一般的だ。また、イタリアの税務当局への登録も、本番環境で利用する際には必要となる。開発環境としては、VS Codeというテキストエディタと、そのC#開発を便利にするための拡張機能「C# Dev Kit」が推奨されているが、Visual Studioなど他の統合開発環境でも同様に進められる。

準備が整ったら、いよいよアプリケーションの作成に入る。最初のステップは、新しいC#のコンソールアプリケーションプロジェクトを作成することだ。コマンドプロンプトやターミナルで「dotnet new console -n send」と入力すると、「send」という名前の新しいプロジェクトが作成される。次に、作成された「send」ディレクトリに移動し、「dotnet add package Invoicetronic.Sdk」というコマンドを実行して、先ほど説明したInvoicetronic SDKをプロジェクトに追加する。これにより、Invoicetronic APIと連携するための便利なプログラム部品が利用可能となる。

SDKをプロジェクトに追加したら、次はSDKの設定を行う。VS Codeでプロジェクトを開き、「Program.cs」というファイルを開く。このファイルに、Invoicetronic APIに接続するための情報を記述するのだ。具体的には、Invoicetronic.Sdk.Api、Invoicetronic.Sdk.Client、Invoicetronic.Sdk.Modelという名前空間（関連するクラスや関数をまとめたグループ）をプログラムの冒頭で宣言し、そして「Configuration」というクラスのインスタンスを作成する。このConfigurationオブジェクトには、APIの接続先URL（BasePath）と、取得したテスト用のAPIキー（Username）を設定する。APIキーは通常、認証情報としてHTTPリクエストのヘッダーなどで送られるが、このSDKではUsernameプロパティを使って設定する形式になっている点に注目だ。

設定が完了すれば、いよいよ請求書を送信する処理を記述できる。まず、送信したい請求書ファイル（XML形式）のパスをプログラム内で指定する。また、請求書に紐づける「メタデータ」も設定できる。メタデータとは、請求書そのものの内容とは別に、システム内部で管理したい付加情報のことだ。例えば、社内管理用のIDや、どのアプリケーションで作成されたかといった情報をDictionaryという形式で自由に設定できる。

次に、「SendApi」というクラスのインスタンスを作成する。これは、Invoicetronic APIの「請求書を送信する」という機能（エンドポイント）と連携するための専用クラスである。このSendApiのインスタンスに対して、先ほど設定したConfigurationオブジェクトを渡すことで、どのAPIに、どの認証情報で接続するかを教えている。

そして、実際に請求書を送信するコードを書く。SendApiの「SendPostAsync」という非同期メソッドを呼び出す。このメソッドには、「Send」というクラスのインスタンスを引数として渡す。Sendクラスのインスタンスには、請求書のファイル名（FileName）、請求書の内容（Payload）、そしてオプションのメタデータ（MetaData）を設定する。Payloadには、ファイルから読み込んだXML形式の請求書データそのものを文字列として格納する。非同期メソッドなので「await」キーワードを使い、APIからの応答を待つ。請求書の送信が成功した場合、APIからは送信された請求書の一意なIDが返されるので、それをコンソールに出力して確認する。もしAPIとの通信でエラーが発生した場合は、「try-catch」構文を使ってそのエラーメッセージとエラーコードを表示し、プログラムが予期せぬ停止をしないようにする。これはエラーハンドリングと呼ばれる、堅牢なシステムを作る上で非常に重要な技術である。

これらのコードを記述し終えたら、ターミナルで「dotnet run」コマンドを実行する。これによりC#アプリケーションがコンパイルされ、実行される。全てが正しく設定されていれば、「請求書は正常に送信され、一意なIDが割り当てられました」といったメッセージが表示されるはずだ。

このチュートリアルを通して、私たちはいくつかの重要なことを学ぶことができた。第一に、外部のAPIサービスを利用する際には、まずSDKの設定としてAPIの接続先パスと認証情報（APIキー）を正しく設定する必要があること。第二に、APIの特定のエンドポイントと連携するためには、それに対応するクラス（今回の場合はSendApi）をインスタンス化する必要があること。そして第三に、APIに送信するデータは、SDKが提供するモデルクラス（今回の場合はSend）に沿って、必要なプロパティ（FileName、Payload、MetaDataなど）を設定する必要があること。特にPayloadプロパティは、実際に送りたい請求書データ本体を格納する場所である。

システムエンジニアを目指す上で、外部サービスやAPIと連携してシステムを構築する能力は非常に重要だ。今回の経験は、その基礎を築くための貴重な一歩となるだろう。