How to Create a ZUGFeRD PDF with PHP

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

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 PHP 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 PHP samples use Guzzle and PSR-7 stream utilities. Install Guzzle with Composer when moving the code outside the repository and supply the API key through protected configuration.

How to Create a ZUGFeRD PDF with PHP Code Example

require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\Psr7\Utils;

// 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.
$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
 */
//$apiUrl = 'https://eu-api.pdfrest.com';

// Set these paths to your CII XML invoice and the corresponding visual PDF.
$apiKey = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
$invoiceXml = '/path/to/invoice.xml';
$invoicePdf = '/path/to/invoice.pdf';

$client = new Client();
$headers = ['Accept' => 'application/json', 'Api-Key' => $apiKey];

// 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.
$options = [
    'multipart' => [
        ['name' => 'file', 'contents' => Utils::tryFopen($invoiceXml, 'r'), 'filename' => basename($invoiceXml), 'headers' => ['Content-Type' => 'application/xml']],
        ['name' => 'pdf_file', 'contents' => Utils::tryFopen($invoicePdf, 'r'), 'filename' => basename($invoicePdf), 'headers' => ['Content-Type' => 'application/pdf']],
        ['name' => 'regenerate_pdf', 'contents' => 'true'],
        ['name' => 'render_options', 'contents' => json_encode(['locale' => 'de-DE', 'label_language' => 'de', 'font' => 'arial', 'bold_font' => 'arialbold', 'accent_color_rgb' => [0, 92, 171]])],
        ['name' => 'output', 'contents' => 'zugferd_invoice'],
    ]
];

$request = new Request('POST', $apiUrl . '/zugferd-pdf', $headers);
$response = $client->sendAsync($request, $options)->wait();

echo $response->getBody();

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. Guzzle receives the multipart body as an array. File entries provide an opened stream, filename, and content type; text entries carry the ordinary API options.
• Configure the request safely. Configure the endpoint, key, and input paths before running the sample. Use Composer-managed Guzzle dependencies and keep the credential in protected application configuration.
• 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 body is printed as JSON. Check the HTTP status before accepting the result so an error document is not confused with a successful output or validation response.

Beyond the Tutorial

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