`invoice` Quickstart

You don't need to learn the API or any programming language to send and receive invoices. We created the invoice command to quickly and intuitively exchange invoice file(s) with the Servizio di Interscambio (SDI) from the command line.

In this quickstart we'll use the invoice command line tool to:

Send invoice file(s) to the SDI
Receive invoices from the SDI
Configure the tool for optimum usage

Prerequisites

We assume that these prerequisites are met:

invoice is installed on your system.
You obtained an active API Key.
You registered with the Italian Revenue Service (needed for the live environment)

Warning

In all examples, remember to replace the example key with your test api key. Do not use your live key, or the documents will be sent to the SDI for actual delivery.

Send

The send command lets you upload invoice file(s) to the SDI. For example:

invoice send file1.xml --apikey ik_test_YOUR_API_KEY

Uploads file1.xml to the Sandbox for test purposes.

You can list multiple files:

invoice send file1.xml file2.xml path/to/another/file3.xml.p7m --apikey ik_test_YOUR_API_KEY

The above uploads file1.xml and file2.xml from the current directory, and the digitally signed file3.xml.p7m from a different path.

Bulk uploads are probably better served with wildcards:

invoice send outbound/*.xml --apikey ik_test_YOUR_API_KEY

Uploads all xml invoice files from outbound directory.

Delete after upload

You may want to get rid of the local files once they are uploaded. That is achieved with the --delete option:

invoice send file1.xml --delete --apikey ik_test_YOUR_API_KEY

Performs as the previous command, but the local files will be removed on successful uploads.

Pre-flight validation

If you are unsure whether the invoices are valid for the SDI, you can ask for pre-flight validation with the --validate option:

invoice send file1.xml --validate --apikey ik_test_YOUR_API_KEY

The file will be rejected on validation failure.

Asking for help

invoice send --help

Lists all the available options, and show how to use them.

Receive

The receive command lets up download invoices from the SDI.

invoice receive --apikey ik_test_YOUR_API_KEY

Not receiving invoices in the live environment?

Ensure your correspondents use 7HD37X0 as the value of their invoices' Codice Destinatario field. That is how SDI knows they should be forwarded to the Invoicetronic API.

Unread invoices only

Downloads all available invoice files. This may download previously downloaded files, though. If you're only intersted in new invoices, use the --unread option:

invoice receive --unread --apikey ik_test_YOUR_API_KEY

Now, only previusly unread invoices will be downloaded. If you want to only keep fresh invoices on the API, you can use the --delete option flag:

Delete once downloaded

invoice receive --delete --apikey ik_test_YOUR_API_KEY

With the above, once an invoice has been downloaded and saved to disk, it will be removed from the remote.

As JSON

By default, downloaded invoices are stored as files according to their file_name field value. If you need to immediately process the document, possibly with a Linux pipeline, you may prefer a JSON output to stdout:

invoice receive --json --apikey ik_test_YOUR_API_KEY | more

The command above will display the invoice on the console, pausing when the screen is full.

Configure

Having to repeat the API key on every command is tedious. You can use the config command to persist the key in a configuration file:

invoice config apikey ik_test_YOUR_API_KEY

Now you can omit the key when you issue a send or receive command:

invoice receive --unread

or:

invoice send file.xml

Etc. The configuration file is stored in the user's home directory with the .invoice.yaml name (it is hidden on Unix/Linux systems). There are more configuration options, to see them all simply use the --list (-l)option flag:

invoice config --list

Configuration file: /Users/johndoe/.invoice.yaml
apikey: ik_test_YOUR_API_KEY
host: https://api.invoicetronic.com
verbose: false

You can also edit the configuration at once with invoice config --edit (or -e).

As you can see, you can switch to a verbose mode (invoice config verbose true), set a different host (currently not very useful), see where the configuration is held.

Environment variables

When you save the api key in your configuration, it is stored as clear text. If security is a concern (it should), you want to use environment variables instead:

INVOICE_APIKEY=ik_test_MY_SUPER_SECRET_KEY invoice config -l

Configuration file: /Users/johndoe/.invoice.yaml
apikey: ik_test_MY_SUPER_SECRET_KEY     # we're running with the key from the envvar
host: https://api.invoicetronic.com
verbose: false

By prepending INVOICE_ to any configuration setting, you can pass it as an environment variable, never storing the sensitive data on your system. A more useful example:

INVOICE_APIKEY=ik_test_MY_SUPER_SECRET_KEY invoice send file1.xml

In a continous integration environment, you want the envvar value sourced from a secret of some kind (GitHub Secrets, etc.)

invoice Quickstart