/invoice/transform-and-create als veraltet. Er wird in der nächsten Version 2.x.x der Software entfernt. Der einzig notwendige Schritt ist /invoice/transform-and-create mit /invoice/create zu ersetzen. Die Parameter bleiben die gleichen.
[% END %]
### Einfache E-Rechnung
In seiner einfachsten Form, lässt sich eine E-Rechnung aus Tabellenkalkulations-Daten folgendermaßen erzeugen:
[% FILTER $CodeGroup %]
[curl]
[% FILTER $Highlight "language-sh" %]
curl -X POST http://localhost:3000/api/invoice/create/UBL \
-F data=@contrib/templates/default-invoice.ods \
-F mapping=@contrib/mappings/default-invoice.yaml
[% END %]
[httpie]
[% FILTER $Highlight "language-sh" %]
http --form POST http://localhost:3000/api/invoice/create/UBL \
data@contrib/templates/default-invoice.ods \
mapping@contrib/mappings/default-invoice.yaml
[% END %]
[% END %]
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.
Die Rechnungsdaten (Parameter `data`) werden aus der Tabellenkalkulations-Datei `contrib/templates/default-invoice.ods` gelesen. Diese Daten werden dann mit der Mapping-Definition in `contrib/mappings/default-invoice.yaml` auf die E-Rechnungsdaten abgebildet.
### E-Rechnung mit zusätzlichen Attachments
Es ist möglich, weitere Dateien mit zusätzlichen Informationen anzuhängen. Dies funktioniert sowohl für reine XML-Formate als auch für hybride Factur-X/ZUGFeRD-E-Rechnungen. Dieses Beispiel erzeugt eine Factur-X-Rechnung mit dem Profile „Extended“ mit zwei Attachments:
[% FILTER $CodeGroup %]
[curl]
[% FILTER $Highlight "language-sh" %]
curl -X POST \
http://localhost:3000/api/invoice/create/UBL \
-F lang=de \
-F data=@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"
[% END %]
[httpie]
[% FILTER $Highlight "language-sh" %]
http --form POST http://localhost:3000/api/invoice/create/UBL \
lang=de \
data@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"
[% END %]
[% END %]
Die Bedeutungen der einzelnen URL-Parameter sind:
* `lang`: Wird für die Übersetzung einiger Standardtexte verwendet .
* `data`: Die Tabellenkalkulations-Datei mit den Rechnungsdaten.
* `mapping`: Die Mapping-Definition für die Zuordnung der Rechnungsdaten.
* `embedPDF`: Bewirkt, dass eine PDF-Version der E-Rechnung in XML eingebettet wird; ignoriert für Factur-X/ZUGFeRD.
* `pdf`: Die PDF-Version der E-Rechnung. Falls die Einbettung gewünscht ist, der Parameter `pdf` jedoch nicht angegeben wurde, wird das PDF aus der Tabellenkalkulations-Datei (Parameter `data`) erzeugt.
* `pdfID`: Die Attachment-ID des eingebetteten PDFs. Standardwert ist der Dateiname.
* `pdfDescription`: Eine optionale Beschreibung des Dateianhangs.
* `attachment`: Optional, eine zusätzlich einzubettende Datei.
* `attachmentID`: Optional, die ID des Dateianhangs. Standardwert ist der Dateiname.
* `attachmentDescription`: Eine optionale Beschreibung des Dateianhangs.
[% title = "PDF aus Tabellenkalkulations-Daten erzeugen" %]
[% WRAPPER components/infobox.html type='warning' title=title %]
Wird das PDF nicht mit dem Parameter pdf übergeben, wird es aus der Tabellenkalkulations-Datei (Parameter data) erzeugt. In diesem Fall muss sichergestellt werden, dass die ausführbare LibreOffice-Datei gefunden wird. Sie muss entweder in $PATH liegen, oder ihr genauer Ort muss konfiguriert werden.
[% END %]
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:
| Anhang | Dateiname | ID | Beschreibung |
|—————————|————————|——|——————|
| **Anhang #1** | `attachment` #1 | `attachmentID #1` | `attachmentDescription #1` |
| **Anhang #2** | `attachment` #2 | `attachmentID #2` | `attachmentDescription #2` |
| **Anhang #3** | `attachment` #3 | - | `attachmentDescription #3` |
| **Anhang #4** | `attachment` #4 | - | - |
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.
[% FILTER $CodeGroup %]
[curl]
[% FILTER $Highlight "language-sh" %]
curl -X POST http://localhost:3000/api/invoice/create/Factur-X-Extended \
-F data=@contrib/templates/default-invoice.ods \
-F mapping=@contrib/mappings/default-invoice.yaml >e-invoice.pdf
[% END %]
[httpie]
[% FILTER $Highlight "language-sh" %]
http --form POST http://localhost:3000/api/invoice/create/Factur-X-Extended \
data@contrib/templates/default-invoice.ods \
mapping@contrib/mappings/default-invoice.yaml >e-invoice.pdf
[% END %]
[% END %]
Dies würde eine E-Rechnung im Format Factur-X/ZUGFeRD mit dem Profil *Extended* erzeugen.
Man muss sich allerdings vergegenwärtigen, dass das hybride Format Factur-X/ZUGFeRD eine PDF-Version *verlangt*. Diese PDF-Version muss entweder mit dem Parameter `pdf` übergeben werden, oder `LibreOffice` muss verfügbar sein, damit sie aus der Tabellenkalkulations-Datei `data` erzeugt werden kann.
## Rechnungen aus JSON erzeugen
Das Mapping, also die Zuordnung von Tabellendaten zu Rechnungsdaten kann auch übersprungen werden. Dafür muss lediglich der Parameter `mapping` weggelassen werden.
Beispiel:
[% FILTER $CodeGroup %]
[curl]
[% FILTER $Highlight "language-sh" %]
curl -X POST http://localhost:3000/api/invoice/create/UBL \
-F invoice=@contrib/data/default-invoice.json
[% END %]
[httpie]
[% FILTER $Highlight "language-sh" %]
http --form POST http://localhost:3000/api/invoice/create/UBL \
invoice@contrib/data/default-invoice.json
[% END %]
[% END %]
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](#e-invoice-with-additional-attachments), 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]([% q.llink(name='internal-format') %]) aus einer Tabellendatei erzeugen. Das ergibt vermutlich nur für Informationszwecke Sinn, weil JSON kein erlaubtes Format für E-Rechnungen ist.
Beispiel:
[% FILTER $CodeGroup %]
[curl]
[% FILTER $Highlight "language-sh" %]
curl -X POST http://localhost:3000/api/mapping/transform/UBL \
-F data=@contrib/templates/default-invoice.ods \
-F mapping=@contrib/mappings/default-invoice.yaml
[% END %]
[httpie]
[% FILTER $Highlight "language-sh" %]
http --form POST http://localhost:3000/api/mapping/transform/UBL \
data@contrib/templates/default-invoice.ods \
mapping@contrib/mappings/default-invoice.yaml
[% END %]
[% END %]
Dieser Endpunkt erlaubt nur zwei Parameter:
* `data`: Die Tabellendatei mit den Rechnungsdaten.
* `mapping`: Die Mapping-Definition für die Rechnungsdaten.
[% title = "Weshalb wird das Format benötigt?" %]
[% WRAPPER components/infobox.html type='info' title=title %]
Dieser Endpunkt bildet Daten aus einer Tabellendatei in das [interne Format]([% q.llink(name='internal-format') %]) ab, was eigentlich unabhängig vom Ausgabeformat sein sollte. Das Format muss dennoch angegeben werden, weil die Transformierung auch die Customization-ID im Feld `/ubl:Invoice/cbc:customizationID` einfügt. Wird die Customization-ID mit der Tabelle übergeben, kann ein beliebiges Format angegeben werden, weil eine explizit angegebene Customization-ID nie überschrieben wird.
[% END %]