Automation MCP Server Blog Pricing
API

Generating Invoice PDFs in Code: PDF/A-3 with the E-Invoice Inside, from JSON

A PDF library draws a page. An invoice PDF today must also carry the invoice as structured data, follow the e-invoicing rules and pass validation. This guide shows how to get all of that from one call: you send the invoice as JSON and get back a finished PDF/A-3 with the XML inside, in your design and your language.

This guide is for developers who need to create invoice PDFs from their own application. It explains why a PDF library alone is no longer enough, and how one API call returns a complete e-invoice PDF instead. The examples use the ZUGFeRD format for Germany. Factur-X for France works the same way.


What an invoice PDF must be today

For years, an invoice PDF only had to look right. That is changing. Germany and France are moving B2B invoices to e-invoices: invoices that software can read without a person typing them in. The mandate map lists the dates.

A hybrid PDF meets both needs in one file. ZUGFeRD in Germany and Factur-X in France work like this:

  • The page is for people. It looks like a normal invoice, with your logo and layout.
  • The XML inside is for software. It holds every invoice field in the European standard EN 16931. The buyer's accounting system reads it directly.
  • The file is a PDF/A-3. This archive format allows embedded files and keeps the invoice readable for many years.

So "generate an invoice PDF" now means three jobs: draw the page, build the XML, and make sure both follow the rules.


What a PDF library leaves to you

A PDF library draws text, tables and images. That covers the page. Everything else stays with your team:

  • The XML. Hundreds of fields, each with a business term ID, a code list and a place in the CII structure.
  • The calculation. Line amounts, allowances, the VAT breakdown per rate and the totals, rounded the way the rules expect.
  • The PDF/A-3 container. Embedded fonts, a colour profile, the XMP metadata that declares the profile, and the attachment relationship.
  • The validation. The XML schema, the EN 16931 rules and the national rules, run on every invoice before it leaves.
  • The updates. The rule sets change, and each change must be in production on its effective date.

Each of these is a project of its own. An API that does all five turns them into one request.


One call: JSON in, PDF/A-3 out

POST /v1/create/zugferd takes the invoice as JSON. The API calculates the totals, builds the XML, draws the page, embeds the XML in a PDF/A-3 and validates the result. The response is the finished PDF.

curl -X POST https://api.invoicexml.com/v1/create/zugferd \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": {
      "invoiceNumber": "RE-2026-1187",
      "issueDate": "2026-11-16",
      "dueDate": "2026-12-16",
      "currency": "EUR",
      "seller": {
        "name": "Elbwerk Software GmbH",
        "vatIdentifier": "DE811234567",
        "postalAddress": { "line1": "Hafenstraße 12", "postCode": "20457", "city": "Hamburg", "country": "DE" }
      },
      "buyer": {
        "name": "Contoso Handel GmbH",
        "postalAddress": { "line1": "Zeil 65", "postCode": "60313", "city": "Frankfurt am Main", "country": "DE" }
      },
      "paymentDetails": { "paymentMeansCode": "58", "paymentAccountIdentifier": "DE02120300000000202051" },
      "lines": [
        {
          "quantity": 10,
          "unitCode": "HUR",
          "item": { "name": "Software development" },
          "priceDetails": { "netPrice": 95.50 },
          "vatInformation": { "rate": 19, "categoryCode": "S" }
        }
      ]
    }
  }' \
  --output invoice.pdf

You send no totals. The API works out 955.00 net, 181.45 VAT and 1,136.45 to pay, writes them into the XML and prints them on the page. For France, send the same body to POST /v1/create/facturx and get a Factur-X PDF.


The same call with an SDK

The official SDKs wrap these calls for .NET, Java, PHP, Node.js and Python. They give you typed invoice models, so your editor completes every field. There is one package per market: ZUGFeRD and XRechnung for Germany, Factur-X for France.

# pip install invoicexml-zugferd-xrechnung
from pathlib import Path
from invoicexml_zugferd_xrechnung import *

client = ZugferdXRechnungClient()      # reads the API key from INVOICEXML_API_KEY
invoice = InvoiceDocument(
    invoice_number="RE-2026-1187", issue_date="2026-11-16", currency="EUR",
    seller=SellerParty(name="Elbwerk Software GmbH", vat_identifier="DE811234567",
                       postal_address=SellerPostalAddress(line1="Hafenstraße 12", city="Hamburg",
                                                          post_code="20457", country="DE")),
    buyer=BuyerParty(name="Contoso Handel GmbH",
                     postal_address=BuyerPostalAddress(line1="Zeil 65", city="Frankfurt am Main",
                                                       post_code="60313", country="DE")),
    payment_details=PaymentDetails(payment_account_identifier="DE02120300000000202051"),
    lines=[InvoiceLine(quantity=10, item=ItemInformation(name="Software development"),
                       price_details=PriceDetails(net_price="95.50"),
                       vat_information=LineVatInformation(rate=19))],
)
Path("invoice.pdf").write_bytes(client.create_zugferd(invoice))
// npm install @invoicexml/zugferd-xrechnung
import { writeFile } from "node:fs/promises";
import { ZugferdXRechnungClient } from "@invoicexml/zugferd-xrechnung";

const client = new ZugferdXRechnungClient({ apiKey: process.env.INVOICEXML_API_KEY! });
await writeFile("invoice.pdf", await client.createZugferd(invoice));   // invoice: the same fields as above
// dotnet add package InvoiceXml.Zugferd.XRechnung
using InvoiceXml.Zugferd.XRechnung;

using var client = new ZugferdXRechnungClient("YOUR_API_KEY");
var pdf = await client.CreateZugferdAsync(invoice);   // invoice: an InvoiceDocument with the same fields
await pdf.SaveAsync("invoice.pdf");

The packages are open source under the MIT licence. The rules run on the server, so you do not update the package when a new ZUGFeRD or Factur-X version comes out. The language guides go deeper for Python, Node.js, C#, PHP and Java.


Make the PDF look like yours

The built-in layout is a clean, standard invoice. The options object next to invoice adapts it to your brand:

OptionWhat it does
languagePrints the labels and dates in EN, DE or FR. Your own text stays as you wrote it.
logoUrl or logoPrints your logo at the top left. logoUrl is a public link, logo is the image itself in base64.
brandColorColours the headings and accents, for example #173A40.
includeQrCodeAdds a payment QR code. The buyer scans it with a banking app and the transfer is filled in.
includeAdvancedPropertiesAdds a section with the technical details, such as the electronic addresses and the profile.
pdfUrlUses your own PDF as the page. The API embeds the generated XML into it.
{
  "invoice": { ... },
  "options": {
    "language": "DE",
    "logoUrl": "https://www.example.com/logo.png",
    "brandColor": "#173A40",
    "includeQrCode": true
  }
}

The payment QR code appears when the invoice is in euros, has a valid IBAN, uses a credit transfer as the payment means and has an amount to pay. In the SDKs the same settings are options on the create call, for example InvoiceOptions(language=PdfLanguage.DE, logo_url="...") in Python.

Do you already create your invoice PDFs and only need the XML inside? Then the embed endpoints take your PDF and your XML and return the hybrid PDF/A-3.


When the data is wrong

The API checks every invoice before it returns the PDF. If the data breaks a rule, you get HTTP 400 and no file. The response lists each finding with the rule, the field in your JSON and a message that says how to fix it:

try:
    pdf = client.create_zugferd(invoice)
except InvoiceValidationError as e:
    for finding in e.errors:
        print(finding.rule, finding.fields, finding.message)

Because every finding names the JSON field, your application can show the message next to the right input. An invalid invoice never reaches your customer.


Send the PDF by email

Most invoices go out by email. POST /v1/create/zugferd/email creates the PDF, validates it and sends it to your customer from your own domain, in one call. You verify the sending domain once in the dashboard.

result = client.email_zugferd(invoice, EmailMessage(
    from_="[email protected]", to="[email protected]",
    subject="Invoice RE-2026-1187"))
print(result.status, result.message_id)

Readable PDFs from XML invoices

Some e-invoices have no page at all. XRechnung and Peppol UBL invoices are XML only. When a person needs to see one, POST /v1/render/xml/to/pdf turns the XML into a readable PDF, with the same language and QR code options. The XML to PDF guide shows this in detail. The PDF is a copy for people. The XML stays the invoice.


Get started

An invoice PDF today is a page, an XML file and a set of rules. One call creates all three from your data, checked and ready to send. Create an account to get an API key and start a free trial. No credit card is needed. The pricing page shows what the trial includes.

Related guides:

Start free today

Ready to automate your invoices?

Validate, convert and embed compliant e-invoices through one API. Start your 30-day free trial. No credit card required.

GDPR Compliant No credit card required Setup in minutes
Peppol UBL
Factur-X
EN 16931
142 / 142 passed
Compliant
PDF/A-3 embedded