XRechnung is a standardized electronic invoice format, widely used in Germany, that complies with the European standard EN 16931, ensuring compliance with EU regulations that require public administrations throughout the EU to be able to process electronic invoices. It is based on XML, making it machine-readable and suitable for automated processing, while also complying with EU Directive 2014/55/EU on electronic invoicing for public procurement.
While current versions of ZUGFeRD are legally compatible with XRechnung, XRechnung doesn't provide a visual representation of the invoice. ZUGFeRD is a hybrid document format with a human-readable form of the invoice in PDF format and an attachment containing the XML. When accepting pure XML that is automatically processed by accounting applications, it may be helpful to visualize the invoice for readability.
Visualizing XRechnung
This article demonstrates how TX Text Control can be used to visualize an invoice by extracting the XML embedded in a PDF or pure XML source and rendering it human-readable.
The example document is a random document from the ZUGFeRD corpus. The ZUGFeRD corpus is a collection of valid documents.
The first step is to use the ServerTextControl to extract the XML from the PDF document. ZUGFeRD-csharp is then used to import the XML, which is then exported as JSON to create the template.
| // Create a new LoadSettings object to specify settings for loading the PDF | |
| TXTextControl.LoadSettings ls = new TXTextControl.LoadSettings() | |
| { | |
| // Configure the settings to load any embedded files from the PDF | |
| PDFImportSettings = TXTextControl.PDFImportSettings.LoadEmbeddedFiles | |
| }; | |
| // Create a new ServerTextControl instance for processing the document | |
| using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl()) | |
| { | |
| // Initialize the TXTextControl instance | |
| tx.Create(); | |
| // Load the PDF document (MustangGnuaccountingBeispielRE-20201121_508-1.pdf) with the specified settings | |
| // The document is loaded from a file and the embedded files are handled according to the settings | |
| tx.Load("MustangGnuaccountingBeispielRE-20201121_508-1.pdf", TXTextControl.StreamType.AdobePDF, ls); | |
| // Extract the first embedded file's data (assumed to be the invoice) from the LoadSettings object | |
| byte[] byteArray = (byte[])ls.EmbeddedFiles[0].Data; | |
| // Convert the byte array to a MemoryStream for further processing | |
| MemoryStream stream = new MemoryStream(byteArray); | |
| // Initialize a list of InvoiceDescriptor objects to store the parsed invoices | |
| List<InvoiceDescriptor> invoices = new List<InvoiceDescriptor>(); | |
| // Load the invoice data from the MemoryStream and add it to the list of invoices | |
| invoices.Add(InvoiceDescriptor.Load(stream)); | |
| // Serialize the list of invoices to JSON format | |
| var jsonInvoice = JsonSerializer.Serialize(invoices); | |
| // Write the serialized JSON data to a file named "invoice.json" | |
| File.WriteAllText("invoice.json", jsonInvoice); | |
| } |
Creating the Template
The generated JSON file is used as a data source in TX Text Control to create a template with the required merge fields and repeating blocks.
In addition to static content and merge fields, the template consists of two merge blocks, one for the line items and one to list the various sales taxes.
Merging the Data
Since ZUGFeRD and XRechnung are based on the same standard, any valid XML document can be used with this created template. Now we can again use the ServerTextControl to extract the XML, convert it to JSON, and then merge that JSON into the template to generate the preview PDF document.
| // Import necessary namespaces for ZUGFeRD, JSON processing, and TXTextControl | |
| using s2industries.ZUGFeRD; | |
| using System.Text.Json; | |
| using System.Text.Json.Nodes; | |
| using TXTextControl.DocumentServer; | |
| // Set up the LoadSettings for TXTextControl, specifically enabling the loading of embedded files in the PDF | |
| TXTextControl.LoadSettings ls = new TXTextControl.LoadSettings() | |
| { | |
| // Specify that embedded files in the PDF should be loaded | |
| PDFImportSettings = TXTextControl.PDFImportSettings.LoadEmbeddedFiles | |
| }; | |
| // Create and use the ServerTextControl instance to process the document | |
| using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl()) | |
| { | |
| // Initialize the TXTextControl object | |
| tx.Create(); | |
| // Load the PDF file into the ServerTextControl instance using the specified load settings | |
| // The file is "MustangGnuaccountingBeispielRE-20201121_508-1.pdf" | |
| tx.Load("MustangGnuaccountingBeispielRE-20201121_508-1.pdf", TXTextControl.StreamType.AdobePDF, ls); | |
| // Extract the first embedded file (expected to be the invoice data) as a byte array from the load settings | |
| byte[] byteArray = (byte[])ls.EmbeddedFiles[0].Data; | |
| // Convert the byte array to a MemoryStream for further processing | |
| MemoryStream stream = new MemoryStream(byteArray); | |
| // Create a list of InvoiceDescriptor objects to store parsed invoices | |
| List<InvoiceDescriptor> invoices = new List<InvoiceDescriptor>(); | |
| // Load the invoice data from the MemoryStream and add it to the list | |
| invoices.Add(InvoiceDescriptor.Load(stream)); | |
| // Serialize the list of invoices to JSON format | |
| var jsonInvoice = JsonSerializer.Serialize(invoices); | |
| // Load a predefined invoice template from a file ("invoice_template.tx") to prepare for mail merge | |
| tx.Load("invoice_template.tx", TXTextControl.StreamType.InternalUnicodeFormat); | |
| // Create a MailMerge object to handle the merging of the JSON data into the template | |
| MailMerge mailMerge = new MailMerge() | |
| { | |
| // Assign the loaded TXTextControl instance (template) as the TextComponent for the mail merge | |
| TextComponent = tx, | |
| }; | |
| // Perform the mail merge operation, injecting the serialized JSON invoice data into the template | |
| mailMerge.MergeJsonData(jsonInvoice); | |
| // Save the merged document as a new PDF file ("results.pdf") | |
| tx.Save("results.pdf", TXTextControl.StreamType.AdobePDF); | |
| } |
The resulting PDF document is a human-readable representation of the XRechnung XML document.
Of course, you can use the above code without extracting the XML document from the PDF if you already have the XML (which is the usual workflow for XRechnung).
Conclusion
TX Text Control can be used to visualize XRechnung XML documents by creating a template with merge fields and repeating blocks. The XML data can be merged into the template to generate a human readable representation of the invoice.
Download the complete project from GitHub.
