5.10. The einvoice FreeMarker directive (for advanced users)

5.10. The einvoice FreeMarker directive (for advanced users)
Prev	Chapter 5. Templates guide: How to create and edit templates for Fanurio	Next

5.10. The einvoice FreeMarker directive (for advanced users)

The einvoice directive is a custom FreeMarker directive implemented in Fanurio that allows you to generate a document from an invoice. It is used mainly to generate the XML document for a ZUGFeRD / Factur-X invoice.

5.10.1. Parameters

The einvoice directive has the following parameters that allow you to specify how the document is generated.

Invoice

The invoice parameter is mandatory and it specifies the invoice for which the document is created. The following example sets this parameter to invoice, the variable that holds the invoice details in an invoice template.
```
[@einvoice invoice=invoice template='fanurio://zugferd2p0basic.ftl' /]
```
Template

The template parameter is mandatory and it allows you to specify the name of the FreeMarker template that is used to generate the document. It can be one of the default templates or a custom template located in the same folder as the template that contains this directive.

The following example uses the fanurio://zugferd2p0basic.ftl default template:
```
[@einvoice invoice=invoice template='fanurio://zugferd2p0basic.ftl' /]
```
The following example uses the mytemplate.ftl custom template that is located in the same folder as the template that contains this directive:
```
[@einvoice invoice=invoice template='mytemplate.ftl' /]
```
Base64 encoding

The base64encoded parameter is optional and it allows you to specify whether the generated output is Base64 encoded or not. If no encoding is specified, the output is not encoded (same as base64encoded=false).
```
[@einvoice invoice=invoice template='fanurio://zugferd2p0basic.ftl' base64encoded=true /]
```

5.10.2. Creating a ZUGFeRD / Factur-X invoice

A ZUGFeRD / Factur-X invoice is a PDF/A-3 compliant PDF file with an attached XML document. The PDF file represents the visual component while the XML document is intended for electronic processing. Fanurio supports all ZUGFeRD versions (1.0, 2.0 and 2.1) and Factur-X version 1.0 which is fully compatible with ZUGFeRD 2.1.

The following instructions explain how to configure an HTML template to include a ZUGFeRD / Factur-X invoice when exported to PDF manually. You can also use the template editor to do the same thing easier.

Set PDF/A version

Add a fanurio-pdf-xmpmetadata meta tag that sets the PDF/A version to 3 and the level of conformance to A, B (recommended) or U.
```
<meta name="fanurio-pdf-xmpmetadata" content="pdfaid.part:3, pdfaid.conformance:B">
```

Set ZUGFeRD / Factur-X version

Add two more properties to the fanurio-pdf-xmpmetadata meta tag to specify the version and conformance level of the format. The mandatory properties required for each format are documented in the following table.

Table 5.22. The properties that define the version and conformance level of each ZUGFeRD version

Format	fanurio-pdf-xmpmetadata	Notes
ZUGFeRD 1.0	zf.Version:1.0, zf.ConformanceLevel:BASIC	The conformance level can have one of the following values: BASIC, COMFORT, EXTENDED
ZUGFeRD 2.0	fx.Version:2p0, fx.ConformanceLevel:BASIC	The conformance level can have one of the following values: MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED
ZUGFeRD 2.1 / Factur-X 1.0	fx.Version:1.0, fx.ConformanceLevel:BASIC	The conformance level can have one of the following values: MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED

The following example sets the ZUGFeRD version to 1.0 and the conformance level to BASIC:

<meta name="fanurio-pdf-xmpmetadata" content="pdfaid.part:3, pdfaid.conformance:B, zf.Version:1.0, zf.ConformanceLevel:BASIC">

Configure the attached file

Add a fanurio-pdf-attachedfile meta tag to set the properties for the attached file. The mandatory properties required for each format are documented in the following table.

Table 5.23. The properties of the attached file for each ZUGFeRD version

Format	fanurio-pdf-attachedfile
ZUGFeRD 1.0	name:ZUGFeRD-invoice.xml, mime:text/xml, relationship:Alternative
ZUGFeRD 2.0	name:zugferd-invoice.xml, mime:text/xml, relationship:Alternative
ZUGFeRD 2.1 / Factur-X 1.0	name:factur-x.xml, mime:text/xml, relationship:Alternative

Besides these properties, the attached file needs two more properties:

description: The description of the attached file.

We recommend using a description that identifies Fanurio as the application that generated the document (see the following example) but you can use anything else.
data: The contents for the attached file specified as a Base64 encoded text.

The contents is generated using the einvoice directive with Base64 encoding enabled (documented above). The template used to generate the contents can be one of the default ones or it can be a custom one if you need to include more details (for instance payment details like IBAN). To create a custom template, start from one of the default templates. Here's a list with the default ZUGFeRD templates:

ZUGFeRD 1.0
ZUGFeRD 2.0
ZUGFeRD 2.1 / Factur-X 1.0

The following example attaches a ZUGFeRD file with version 1.0. It uses the default fanurio://zugferd1p0basic.ftl template to generate the ZUGFeRD file.

<meta name="fanurio-pdf-attachedfile" content="name:ZUGFeRD-invoice.xml, mime:text/xml, relationship:Alternative, description:ZUGFeRD Invoice created by Fanurio, data:[@einvoice invoice=invoice template='fanurio://zugferd1p0basic.ftl' base64encoded=true/]">

Tag the PDF file

Add the fanurio-pdf-tagged meta tag and set it to true to mark the PDF document as tagged.
```
<meta name="fanurio-pdf-tagged" content="true">
```
Embed fonts

Use a custom font like Liberation Sans and add the fanurio-pdf-encoding meta tag to specify an encoding for the fonts.
```
<meta name="fanurio-pdf-encoding" content="Cp1252">

<style>
	body {
		font-family: "Liberation Sans";
	}
</style>
```

The following example shows how to configure a HTML template to create a ZUGFeRD invoice with version 1.0 and BASIC conformance level. The only things you may want to change are the encoding for the PDF fonts and the actual font.

<meta name="fanurio-pdf-xmpmetadata" content="pdfaid.part:3, pdfaid.conformance:B, zf.Version:1.0, zf.ConformanceLevel:BASIC">

<meta name="fanurio-pdf-attachedfile" content="name:ZUGFeRD-invoice.xml, mime:text/xml, relationship:Alternative, description:ZUGFeRD Invoice created by Fanurio, data:[@einvoice invoice=invoice template='fanurio://zugferd1p0basic.ftl' base64encoded=true /]">

<meta name="fanurio-pdf-tagged" content="true">

<meta name="fanurio-pdf-encoding" content="Cp1252">

<style>
	body {
		font-family: "Liberation Sans";
	}
</style>

ZUGFeRD documents created by Fanurio can be validated online at ZUGFeRD Community (requires registration).

Prev	Up	Next
5.9. The qrcode FreeMarker directive (for advanced users)	Home	5.11. The qrbill FreeMarker directive (for advanced users)