ZUGFeRD e-invoicing

pdfMachine ZUGFeRD

ZUGFeRD is a German e-invoicing standard based around PDF and XML file formats. Its poised to change way invoices are handled and can be used by any sort of business. It will make invoice processing more efficient for you and your customers.

A ZUGFeRD PDF is a PDF file that contains the text and graphics that make up a invoice, just like any other PDF. The PDF also contains structured invoice data in an embedded XML document that can be processed by ZUGFeRD compliant applications. A ZUGFeRD PDF is PDF/A-3 compliant. PDF/A-3 is an ISO standard for long term archiving.

The ZUGFeRD standard is documented at the site: www.ferd-net.de

An example of a ZUGFeRD PDF created by pdfMachine : ZUGFeRD_example_invoice_en.pdf
To see the embedded XML, download and open the PDF.

pdfMachine generates ZUGFeRD invoices!

If you are currently printing your invoices, with minor changes you can now generate a ZUGFeRD invoice using pdfMachine. pdfMachine can also automatically email them to your customers.

If you already have your PDF invoice in PDFA/3b and you have the XML then you can use the pdfMachine SDK to attach the XML, and have appropriate ZUGFeRD metadata inserted. Find out how to do this here.

How does pdfMachine generate ZUGFeRD invoices?

You begin with a document that has your invoice ready to print. pdfMachine has a template ZUGFeRD XML file that you can set up with commonly used information. You then add to your invoice some pdfMachine commands to create the ZUGFeRD XML information that is pertinent to that particular invoice. When you print the invoice to pdfMachine, the PDF is created, the commands are used to modify the template and embed it into the PDF.

The pdfMachine commands are part of the pdfMachine "parameter parsing" feature. Parameters or "Embedded Commands" can be entered into the originating document to instruct pdfMachine on particular actions to take when generating the PDF. For ZUGFeRD eInvoicing, the parameter are used to modify values in the ZUGFeRD XML template. The commands are then used to create and embed the XML but are not printed in the PDF.

The parameters to create the XML are documented here. You must set pdf/A-3b selected in the pdfMachine options.

Configuring pdfMachine for ZUGFeRD eInvoicing

Set up Parameter Parsing

Set up your pdfMachine options so that Parameter Parsing is enabled.

Select the "Delete the entire page with parameters from PDF" so that the pdfMachine commands will not interfere with how your invoice looks.

pdfMachine installs with a standard ZUGFeRD XML template that is set up for a ZUGFeRD invoice (using the Basic profile). Click the ZUGFeRD button on the parameter parsing options tab to initialize the XML file.

ZUGFeRD template - Set standard static XML values

Use the ZUGFeRD template editor to add details that are common for your invoices. e.g. company name, address, tax id etc.



pdfMachine ZUGFeRD

The XML file generated consists of static values set in the XML template editor and dynamic values set via parameter parsing. Any static values can be overridden by parameters if desired. e.g. you may have different payment terms for different customers. This file is installed into the users Application Data folder under pdfMachine\ZUGFeRD-invoice_basic.xml. You can also edit this file and add in any other XML entries if it is necessary. You can instruct pdfMachine to use a different template this using x_embed command if you wish.

Create the pdfMachine commands

Make sure you put all of the pdfMachine commands in the invoice on a page of their own as that page will not be included as part of the PDF.
Use the "x_embed" command to tell pdfMachine which ZUGFeRD profile you will use. pdfMachine defaults to the Basic profile, if you want to use one of the other profiles then make sure you initialize the XML template appropriately.
Use the "x" commands to set the XML values eg setting the GrantTotalAmount for the invoice.
Use the "x_a" command to set the attributes for an XML values eg setting the unitCode for the BilledQuantity.
Use the "x_clone" command to copy a set of XML values eg creating another line item for the invoice.
e.g. Add an extra page to your invoice with text like this :

//instruct pdfMachine that this is a basic ZUGFeRD profile
#_ x_embed basic _#  

//set some document level information
#_ x ram:LineTotalAmount 845.00 _#
#_ x ram:GrandTotalAmount 1005.55 _#
..
..
//set the values for a line item
#_ x ram:BilledQuantity 5.0000 _#
#_ x_a ram:BilledQuantity unitCode="KGM" _#
#_ x ram:SpecifiedTradeProduct/ram:Name  Rock _#

// create another line item and set the values
#_ x_clone ram:IncludedSupplyChainTradeLineItem _#   // copy previous line item
#_ x_a ram:BilledQuantity unitCode="MTK" _#
#_ x ram:BilledQuantity 5.0000 _#
#_ x ram:SpecifiedTradeProduct/ram:Name  River Pebbles _#
...
...

The actual tag names (e.g. ram:LineTotalAmount) are documented in the ZUGFeRD specification.

pdfMachine uses the commands to modify the XML file. Upon completion it attaches the XML file to the PDF and places appropriate ZUGFeRD MetaData into the PDF. The page with the commands on it are removed from the final PDF.

If you want pdfMachine to email the ZUGFeRD invoice as well then add the email command

#_ email user@broadgun.com _# 
#_ emailsubject ZUGFeRD compliant invoice _# 
#_ EmailAttachmentName invoice.pdf _# 
#_ Emailbody Hi, 
Your ZUGFeRD compliant invoice is attached. _#

Example

When the file ZUGFeRD_example_invoice_en.html is printed from Internet Explorer to the "Broadgun pdfMachine" printer the following ZUGFeRD compliant PDF is generated:

ZUGFeRD_example_invoice.pdf

The PDF can be downloaded and opened to see the embedded XML file called "ZUGFeRD-invoice.xml".