DEV Community

Nicola Iarocci
Nicola Iarocci

Posted on • Originally published at invoicetronic.com

How to download SDI FatturaPA invoices with C#

#programming #tutorials #dotnet #csharp

In this tutorial we build a simple C# console application that connects and authenticates with the Invoicetronic API and downloads incoming invoices from SDI FatturaPA.

Before continuing, make sure all the prerequisites below are met.

Prerequisites

We assume that these prerequisites are met:

We use the dotnet tool and VS Code as they are available on most systems, but you can follow along with your favourite IDE (Visual Studio, Rider, etc.) if you prefer.

For an optimal C# experience in VS Code, you want to ensure that the C# Dev Kit extension is installed and enabled. For more information, see Getting Started with C# in VS Code.

Create the app

The first step is to create the application:

dotnet new console -n receive
Enter fullscreen mode Exit fullscreen mode

The command created a new C# project named "quickstart" in a directory with the same name. Step into that directory:

cd receive
Enter fullscreen mode Exit fullscreen mode

Install the SDK

Once in the quickstart directory, install the C# SDK:

 dotnet add package Invoicetronic.Sdk
Enter fullscreen mode Exit fullscreen mode

Once that's done, open VS Code in the current directory:

code .
Enter fullscreen mode Exit fullscreen mode

Click on the Program.cs file to see its contents in VS Code right pane.

Configure the SDK

Replace Program.cs default content with the following:

using Invoicetronic.Sdk.Api;
using Invoicetronic.Sdk.Client;
using static Invoicetronic.Sdk.Model.Receive;

// Configure the SDK.
var config = new Configuration
{
    BasePath = "https://api.invoicetronic.com/v1",
    Username = "YOUR TEST API KEY (starts with ik_test_)"
};
Enter fullscreen mode Exit fullscreen mode

As you can see, we initialize a Configuration instance by setting the API's base path and your test API Key (not the live one). Notice how we use the Username property to set the API Key.

When you create your account, you obtain a pair of API Keys. One is the test key for the API Sandbox, and the other is the live API's. You can tell the difference because the former starts with ik_test_, while the latter begins with ik_live_. In this tutorial, always use the test key.

Download invoices

We are ready to make a request. We want to download new vendor invoices that may be avaiable from the SDI. Add these lines:


// Download unread invoices.
var receiveApi = new ReceiveApi(config);

try
{
    var inboundInvoices = await receiveApi.ReceiveGetAsync(unread:true, includePayload:true);
    Console.WriteLine($"Received {inboundInvoices.Count} invoices");

    foreach (var invoice in inboundInvoices)
    {
        switch (invoice.Encoding)
        {
            case EncodingEnum.Xml:
                File.WriteAllText(invoice.FileName, invoice.Payload);
                break;
            case EncodingEnum.Base64:
                File.WriteAllBytes(invoice.FileName, Convert.FromBase64String(invoice.Payload));
                break;
        }

        Console.WriteLine($"Downloaded {invoice.FileName} from a vendor with VAT ID {invoice.Prestatore}");
    }
}
catch (ApiException e)
{
    Console.WriteLine($"{e.Message} - {e.ErrorCode}");
}
Enter fullscreen mode Exit fullscreen mode

We set includePayload: true to retrieve the actual invoice content in the Payload property. Without this parameter, the Payload field would be null by default, which increases performance and reduces response size when you only need metadata.

Switch to the terminal then type:

dotnet run
Enter fullscreen mode Exit fullscreen mode

You should obtain an output similar to this one:

Received 3 invoices
Downloaded file1.xml from a vendor with VAT ID IT06157670966
Downloaded file2.xml.p7m from a vendor with VAT ID IT01280270057
Downloaded file3.xml.p7m from a vendor with VAT ID IT01280270057
Enter fullscreen mode Exit fullscreen mode

The files are in the current directory, ready for you to inspect them.

What we learned

In this example, we learned several things.

  1. We must configure the SDK by setting both the BasePath and Username properties, the latter initialized with the API key.

  2. We must instantiate a class representing the endpoint we want to work with. In this case, we leverage ReceiveApi to download incoming invoices.

  3. Endpoint classes like ReceiveApi offer methods for interacting with their target entity. We call ReceiveGetAsync to retrieve invoices. Because we only want new, unread invoices, we pass unread: true. We also pass includePayload: true to retrieve the actual invoice content (if you run the example a second time, you'll likely not receive any invoice unless some has arrived).

  4. The Receive class exposes valuable properties such as Encoding, FileName, and Payload. The last one contains the invoice content, as plain text or Base64-encoded, as described by Encoding.

Top comments (0)