Rechnungen erzeugen

Die Generelle Funktionsweise besteht darin, zuerst die Daten aus der Tabellenkalkulation auf das interne Rechnungsformat in JSON abzubilden, und daraus im nächsten Schritt eine XML-E-Rechnung oder eine hybrid PDF/XML-Datei aus den JSON-Daten zu erzeugen. Es ist aber auch möglich, den Mapping-Schritt zu überspringen und die Rechnung direkt aus den JSON-Daten zu erzeugen.

Voraussetzungen

Bevor begonnen werden kann, müssen die folgenden Voraussetzungen vorliegen:

• 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.
• You have set the necessary environment variables.

E-Invoice-EU verwendet LibreOffice im Headless-Modus, um PDFs aus Tabellenkalkulations-Daten zu erzeugen. Wird dieses Feature nicht genutzt, muss LibreOffice nicht installiert sein. Alternativ kann immer eine PDF-Datei aus anderen Quellen zur Verfügung gestellt werden, statt sie aus der Tabellenkalkulation zu erzeugen.

Rechnungen aus Tabellenkalkulations-Daten erzeugen

Der API-Endpunkt für diese Funktion ist /api/invoice/create/:FORMAT.

Einfache E-Rechnung

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

curl -X POST http://localhost:3000/api/invoice/create/UBL \
 -F spreadsheet=@contrib/templates/default-invoice.ods \
 -F mapping=@contrib/mappings/default-invoice.yaml

http --form POST http://localhost:3000/api/invoice/create/UBL \
 spreadsheet@contrib/templates/default-invoice.ods \
 mapping@contrib/mappings/default-invoice.yaml

Das Format ist ein Pfad-Parameter, der nach dem Endpunkt-Pfad api/invoice/create angegeben wird, in diesem Fall UBL. Groß- und Kleinschreibung spielt bei der Angabe des Formats keine Rolle.

The invoice data (parameter spreadsheet) 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-Rechnung mit zusätzlichen 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:

curl -X POST \
 http://localhost:3000/api/invoice/create/UBL \
 -F lang=de \
 -F spreadsheet=@contrib/templates/default-invoice.ods \
 -F mapping=@contrib/mappings/default-invoice.yaml \
 -F embedPDF=1 \
 -F pdf=@invoice.pdf \
 -F pdfID=1234567890 \
 -F pdfDescription="Invoice as PDF." \
 -F "attachment=@time-sheet.ods;type=application/vnd.oasis.opendocument.spreadsheet" \
 -F "attachmentID=abc-123-xyz" \
 -F attachmentDescription="Detailed description of hours spent." \
 -F attachment=@payment-terms.pdf \
 -F attachmentDescription="Our payment terms"

http --form POST http://localhost:3000/api/invoice/create/UBL \
 lang=de \
 spreadsheet@contrib/templates/default-invoice.ods \
 mapping@contrib/mappings/default-invoice.yaml \
 embedPDF=1 \
 pdf@invoice.pdf \
 pdfID=1234567890 \
 pdfDescription="Invoice as PDF." \
 attachment@time-sheet.ods\;type=application/vnd.oasis.opendocument.spreadsheet \
 attachmentID=abc-123-xyz \
 attachmentDescription="Detailed description of hours spent." \
 attachment@payment-terms.pdf \
 attachmentDescription="Our payment terms"

Die Bedeutungen der einzelnen URL-Parameter sind:

• 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 spreadsheet).
• pdfID: The attachment id of the embedded PDF, defaults to the filename.
• pdfDescription: An optional description of that attachment.
• attachment: Optionally, an additional file to be embedded.
• attachmentID: Optionally, the id of the attachment, defaults to the filename.
• attachmentDescription: An optional description of the attachment.

The last group of parameters attachment, attachmentID is used twice for two additional attachments. The last attachment does not have an ID.

Jeder Anhang an die E-Rechnung kann eine optionale ID und eine optionale Beschreibung erhalten. Der Service „sieht” allerdings nur 3 Listen der URL-Parameter attachment, attachmentID und attachmentDescription, selbst wenn sie pro Anhang gruppiert wurden.

Wird der Paramter Attachment viermal, attachmentID zweimal und attachmentDescription dreimal angegeben, ganz gleich in welcher Reihenfolge, werden die folgenden Anhänge eingebettet:

Normalerweise wird man diesen Komplikationen aus dem Wege gehen wollen und entweder für jeden Anhang eine ID und/oder Beschreibung übergeben oder für keinen.

Beispiel für Factur-X/ZUGFeRD

Die Erzeugung von Factur-X/ZUGFeRD unterscheidet sich eigentlich nur darin, dass die Ausgabe binär ist, und deshalb in eine Datei umgeleitet werden sollte.

curl -X POST http://localhost:3000/api/invoice/create/Factur-X-Extended \
 -F spreadsheet=@contrib/templates/default-invoice.ods \
 -F mapping=@contrib/mappings/default-invoice.yaml \
 --output e-invoice.pdf

http --form POST http://localhost:3000/api/invoice/create/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 parameter pdf or LibreOffice must be available so that it can be generated from the spreadsheet file spreadsheet.

Rechnungen aus JSON erzeugen

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

Beispiel:

curl -X POST http://localhost:3000/api/invoice/create/UBL \
 -F invoice=@contrib/data/default-invoice.json

http --form POST http://localhost:3000/api/invoice/create/UBL \
 invoice@contrib/data/default-invoice.json

In diesem Fall wird ein Peppol-UBL-Rechnung erzeugt.

Dieser Endpunkt erlaubt exakt die gleichen URL-Parameter wie der Endpunkt für die Erzeugung von Rechnungen aus Tabellen-Daten, bis auf den Parameter mapping der hier keinen Sinn ergibt.

JSON-Daten aus Tabellendaten erzeugen

Mit dem API-Endpunkt /api/mapping/transform/:FORMAT lassen sich Rechnungsdaten im internen Format aus einer Tabellendatei erzeugen. Das ergibt vermutlich nur für Informationszwecke Sinn, weil JSON kein erlaubtes Format für E-Rechnungen ist.

Beispiel:

curl -X POST http://localhost:3000/api/mapping/transform/UBL \
 -F spreadsheet=@contrib/templates/default-invoice.ods \
 -F mapping=@contrib/mappings/default-invoice.yaml

http --form POST http://localhost:3000/api/mapping/transform/UBL \
 spreadsheet@contrib/templates/default-invoice.ods \
 mapping@contrib/mappings/default-invoice.yaml

Dieser Endpunkt erlaubt nur zwei Parameter:

• spreadsheet: The spreadsheet with the invoice spreadsheet.
• mapping: The mapping definition for the invoice data.