How to Create a ZUGFeRD PDF with cURL

Share this page

This tutorial shows how to create a ZUGFeRD or Factur-X hybrid PDF/A-3 invoice with cURL. 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 cURL?

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 cURL 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 shell sample uses cURL directly. Set the service URL, API key, and local input paths near the top of the script before running it.

How to Create a ZUGFeRD PDF with cURL Code Example

#!/bin/sh

# Create a ZUGFeRD / Factur-X PDF/A-3 invoice from XML and an existing invoice PDF.
# By default, we use the US-based API service. This is the primary endpoint for global use.
API_URL="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
# API_URL="https://eu-api.pdfrest.com"

# Replace the API key and invoice paths below with your own values.
API_KEY="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Replace with your API key
INVOICE_XML="/path/to/invoice.xml"
INVOICE_PDF="/path/to/invoice.pdf"

# pdfRest preserves the supplied PDF when it agrees with the canonical XML.
# `regenerate_pdf` enables a fallback replacement PDF for a mismatch or unconfirmed match.
# `render_options` style that fallback PDF only; they do not alter a preserved supplied PDF.
curl --location "$API_URL/zugferd-pdf" \
  --header "Accept: application/json" \
  --header "Api-Key: $API_KEY" \
  --form "file=@$INVOICE_XML;type=application/xml" \
  --form "pdf_file=@$INVOICE_PDF;type=application/pdf" \
  --form "regenerate_pdf=true" \
  --form 'render_options={"locale":"de-DE","label_language":"de","font":"arial","bold_font":"arialbold","accent_color_rgb":[0,92,171]}' \
  --form "output=zugferd_invoice"

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. curl --form builds the multipart body. The @ prefix uploads a local file, and cURL supplies the multipart boundary automatically.
Configure the request safely. Set API_URL, API_KEY, and the local input paths near the beginning of the script. The commented EU URL is an optional regional service setting.
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. The command prints the service response. In an application script, inspect the HTTP result and JSON before treating a returned resource ID or validation result as usable.

Beyond the Tutorial

In this cURL 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 cURL. 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.