How to Create a ZUGFeRD PDF with JavaScript in NodeJS

Share this page

This tutorial shows how to create a ZUGFeRD or Factur-X hybrid PDF/A-3 invoice with JavaScript in NodeJS. It uses the pdfRest Create ZUGFeRD PDF API Tool to send canonical invoice XML and a visual invoice PDF, then returns a managed invoice resource for the next step in the workflow.

Why Create a ZUGFeRD PDF with JavaScript in NodeJS?

Electronic invoicing programs increasingly require an invoice that people can read and systems can process. ZUGFeRD and Factur-X pair a visual PDF with structured invoice XML so finance teams, customers, and downstream systems can work from the same invoice record.

A JavaScript in NodeJS billing service could generate the invoice XML from its accounting data, pair it with a customer-facing PDF, and submit both to pdfRest before delivery. That gives the service a documented API step for producing the hybrid invoice rather than relying on a manual desktop process.

The supplied PDF is retained when it agrees with the canonical XML. With regenerate_pdf=true, the service can create a replacement PDF when it cannot confirm that agreement or finds a mismatch, which gives the workflow a defined fallback instead of silently accepting an uncertain visual invoice.

What the Request Does

The multipart request sends the invoice XML as file and the visual invoice PDF as pdf_file. regenerate_pdf controls the fallback behavior. Optional render_options set locale, label language, fonts, and accent color only for a replacement PDF; they do not alter a supplied PDF that is preserved.

The NodeJS samples use Axios for HTTP, FormData for multipart construction, and streams from the file system for local inputs. Keep the API key in protected runtime configuration rather than in application source.

How to Create a ZUGFeRD PDF with JavaScript in NodeJS Code Example

// Create a ZUGFeRD / Factur-X PDF/A-3 invoice from XML and an existing invoice PDF.
var axios = require('axios');
var FormData = require('form-data');
var fs = require('fs');

// By default, we use the US-based API service. This is the primary endpoint for global use.
var apiUrl = "https://api.pdfrest.com";

/* For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
 * For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
 */
//var apiUrl = "https://eu-api.pdfrest.com";

// Set these paths to your CII XML invoice and the corresponding visual PDF.
var invoiceXml = "/path/to/invoice.xml";
var invoicePdf = "/path/to/invoice.pdf";

var data = new FormData();
data.append('file', fs.createReadStream(invoiceXml));
data.append('pdf_file', fs.createReadStream(invoicePdf));
// pdfRest preserves the supplied PDF when it agrees with the canonical XML.
// Fallback: generate a replacement PDF when the supplied PDF is mismatched or cannot be fully confirmed.
data.append('regenerate_pdf', 'true');
// These styles apply only to that fallback-generated PDF; they do not alter a preserved PDF.
data.append('render_options', JSON.stringify({
  locale: "de-DE", label_language: "de", font: "arial", bold_font: "arialbold",
  accent_color_rgb: [0, 92, 171],
}));
data.append('output', 'zugferd_invoice');

var config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: apiUrl + '/zugferd-pdf',
  headers: {
    'Api-Key': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', // Replace with your API key
    ...data.getHeaders()
  },
  data: data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Source: View the multipart sample on GitHub.

Breaking Down the Code

The request is compact, but each field has a distinct role in the hybrid-invoice workflow.

Identify the two document roles. The file field holds canonical invoice XML, while pdf_file holds the customer-facing invoice PDF. The sample marks them as application/xml and application/pdf, respectively, so the service can distinguish the structured record from its visual companion.
Build the multipart request. FormData receives NodeJS file streams and text fields. Passing form.getHeaders() to Axios is important because it carries the generated multipart boundary.
Configure the request safely. The sample reads local paths and the API key from its configuration values. Keep the key in protected runtime configuration rather than committing it with the application.
Understand the fallback settings. regenerate_pdf=true permits a replacement PDF when pdfRest cannot confirm that the supplied PDF agrees with the XML. The render_options object controls locale, labels, fonts, and accent color for that replacement only; it does not restyle a supplied PDF that pdfRest preserves.
Name and handle the result. output=zugferd_invoice gives the generated resource a useful output name. Axios exposes successful JSON through response.data. Its error path prints the returned API detail when available, which separates a service response from a network or setup failure.

Beyond the Tutorial

In this JavaScript in NodeJS tutorial, you created a ZUGFeRD or Factur-X hybrid invoice from invoice XML and a visual PDF. The response gives the application a managed output resource it can download, deliver, or pass to a following pdfRest operation.

For the complete request fields, accepted values, response contract, and service limits, review the Create ZUGFeRD PDF API Tool documentation. The same endpoint can be used with multipart uploads when the files are present in the current request or with resource IDs after a separate upload step.

The repository also includes a JSON-payload Create ZUGFeRD PDF sample for JavaScript in NodeJS. That version uploads the source files first and then sends their resource IDs to /zugferd-pdf, which is useful when a service already stages input files for later operations.