The Command "invoice"

The General Mode of Operation is to first map spreadsheet data to the internal invoice format in JSON and then generate an e-invoice XML or a hybrid PDF/XML file from that JSON. But it is also possible to bypass the first mapping step and generate the invoice directly from JSON data.

Prerequisites

What you need exactly, depends on the desired output format and your exact requirements. Please see the overview of required arguments in the section FAQ for details.

You need one or more of the following:

• A spreadsheet template. The examples assume that you use the template in contrib/templates/default-invoice.ods.
• A mapping definition. The examples assume that you use the mapping file in contrib/mappings/default-invoice.yaml.
• LibreOffice installed on your system (not always necessary).
• You have started the server. The examples assume that the server is available at http://localhost:3000.
• You have changed directory to the top-level directory of the repository so that the sample files are available.

E-Invoice-EU uses LibreOffice in headless mode to create PDFs from spreadsheet files. If you do not use this feature, there is no need for LibreOffice. Alternatively, you can always provide a PDF file from other sources instead of generating it from spreadsheet data.

Overview of Options and Arguments

The command invoice supports the following options:

Creating Invoices from Spreadsheet Data

Basic E-invoice

In its most simple form, you can create an e-invoice from spreadsheet data like this:

e-invoice-eu --format=UBL \
        --spreadsheet=contrib/templates/default-invoice.ods \
        --mapping=contrib/mappings/default-invoice.yaml

This will create an e-invoice in the format UBL.

The invoice data (option data) is read from the spreadsheet file contrib/templates/default-invoice.ods. That spreadsheet data is then mapped (parameter mapping) with the mapping definition contrib/mappings/default-invoice.yaml.

E-Invoice with Additional Attachments

It is possible to attach files with additional information. This works both for pure XML formats and for hybrid Factur-X/ZUGFeRD e-invoices. The example creates a Factur-X Extended invoice with three attachments:

e-invoice-eu --format=UBL
        --lang=de \
        --spreadsheet=contrib/templates/default-invoice.ods \
        --mapping=@contrib/mappings/default-invoice.yaml \
        --embedPDF \
        --pdf=@invoice.pdf \
        --pdf-id=1234567890 \
        --pdf-description="Invoice as PDF." \
        --attachment=time-sheet.ods \
                --attachment-mimetype=application/vnd.oasis.opendocument.spreadsheet \
        --attachment-d=abc-123-xyz \
        --attachment-description="Detailed description of hours spent." \
        --attachment=payment-terms.pdf \
        --attachment-description="Our payment terms."

Let us break that down into the individual options used:

• --lang: This is used to determine the language for some canned texts.
• --spreadsheet: The spreadsheet with the invoice data.
• --mapping: The mapping definition for the invoice data.
• --embedPDF: Embed a PDF version of the e-invoice in the XML; ignored for Factur-X/ZUGFeRD.
• --pdf: The PDF version of the e-invoice. If embedding a PDF was requested but the parameter pdf is missing, the PDF is generated from the spreadsheet file (parameter data).
• --pdf-id: The attachment id of the embedded PDF, defaults to the filename.
• pdf-description: An optional description of that attachment.
• --attachment: Optionally, an additional file to be embedded.
• --attachment-mimetype: Optionally, the MIME type of the file to be embedded if it not guessed correctly.
• --attachment-id: Optionally, the id of the attachment, defaults to the filename.
• --attachment-description: An optional description of the attachment.

The last group of arguments --attachment is passed twice for two additional attachments. Because the second group omits the option --attachment-description that attachment does not have a description.

Each attachment to the e-invoice may have an optional id and an optional description. However, the program only "sees" 3 lists of the options --attachment, --attachment-mimetype, --attachment-id, and attachment-description, even if you group them per attachment.

If you use the option --attachment four times, --attachment-id twice, and attachment-description three times, in whatever order, the following attachments are embedded:

You will probably want to avoid that hassle by specifying an id and/or description either for all attachments or for none.

Factur-X/ZUGFeRD Example

There is nothing special about creating Factur-X/ZUGFeRD, only that the output is binary and you want to redirect it to a file or use the option --output.

e-invoice-eu --format=Factur-X-Extended \
 --spreadsheet=contrib/templates/default-invoice.ods \
 --mapping=@contrib/mappings/default-invoice.yaml \
 --output e-invoice.pdf

This would create a Factur-X/ZUGFeRD e-invoice with the profile Extended.

You must also keep in mind that the hybrid Factur-X/ZUGFeRD format requires a PDF version of the input. You must either specify it yourself with the option --pdf or LibreOffice must be available so that it can be generated from the spreadsheet file specified as an argument to --spreadsheet.

Creating Invoices from JSON

You can bypass the mapping step and generate the invoice directly from JSON. All you have to do is to omit the parameter mapping.

Example:

e-invoice-eu --forma=UBL --invoice=contrib/data/default-invoice.json

In this case, a Peppol UBL invoice is created.

You can create all other options and arguments that are allowed for the generation of invoices from spreadsheet data with the exception of --mapping which makes no sense.