How to Create a ZUGFeRD PDF with Python

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

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 Python 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 Python samples use requests and requests-toolbelt. Install those packages in the application environment and keep the API key in an environment variable or other secure configuration store.

How to Create a ZUGFeRD PDF with Python Code Example

import json
import os
import requests
from requests_toolbelt import MultipartEncoder

# 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"

# Set these paths to your CII XML invoice and the corresponding visual PDF.
api_key = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
invoice_xml = "/path/to/invoice.xml"
invoice_pdf = "/path/to/invoice.pdf"

# pdfRest preserves the supplied PDF when it agrees with the canonical XML.
# Fallback: generate a replacement PDF for a mismatch or unconfirmed PDF/XML match.
# These styles apply only to that fallback-generated PDF, not to a preserved PDF.
mp_encoder_zugferd = MultipartEncoder(
    fields={
        'file': ('invoice.xml', open(invoice_xml, 'rb'), 'application/xml'),
        'pdf_file': ('invoice.pdf', open(invoice_pdf, 'rb'), 'application/pdf'),
        'regenerate_pdf': 'true',
        'render_options': json.dumps({'locale': 'de-DE', 'label_language': 'de', 'font': 'arial', 'bold_font': 'arialbold', 'accent_color_rgb': [0, 92, 171]}),
        'output': 'zugferd_invoice',
    }
)

headers = {
    'Accept': 'application/json',
    'Content-Type': mp_encoder_zugferd.content_type,
    'Api-Key': api_key
}

print("Sending POST request to zugferd-pdf endpoint...")
response = requests.post(api_url + '/zugferd-pdf', data=mp_encoder_zugferd, headers=headers)
print("Response status code: " + str(response.status_code))
if response.ok:
    print(json.dumps(response.json(), indent=2))
else:
    print(response.text)

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. MultipartEncoder combines file tuples with text fields. Its content_type includes the multipart boundary, so the request headers reuse that value.
• Configure the request safely. Set the service URL, API key, and source paths before running the script. The sample uses requests and requests-toolbelt for the HTTP and multipart work.
• 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 response.ok branch prints formatted JSON; the other branch prints the error response. Treat output identifiers or validation values as application data only from the successful branch.

Beyond the Tutorial

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