Guides

ZUGFeRD PDFs

How to create ZUGFeRD compliant PDFs with finaX.

The finaX e-invoicing API supports generating ZUGFeRD compliant PDFs when creating invoices. Simple PDF generation can be achieved by using the /v1/pdf/json endpoint.

Consider following example:

ZUGFeRD Invoice Payload

{
  "config": {
    "intro_text": "To whom it may concern, please find attached the invoice.",
    "outro_text": "Thank you for your business!",
    "file_name": "invoice.pdf",
    "language": "de"
  },
  "invoice": {
    "invoice_number": "33445566",
    "invoice_issue_date": "2019-08-24",
    "invoice_type_code": 380,
    "invoice_currency_code": "EUR",
    "buyer_reference": "abs1234",
    "payment_terms": "#SKONTO#TAGE=14#PROZENT=2.25#",
    "delivery_information": {
      "actual_delivery_date": "2025-10-10"
    },
    "seller": {
      "name": "Full Formal Seller Name LTD.",
      "vat_identifier": "DE-123",
      "identifier": [
        {
          "scheme_identifier": "0094",
          "value": "Full Formal Seller Name LTD."
        }
      ],
      "electronic_address": {
        "value": "DE123456789",
        "scheme_identifier": "9930"
      },
      "postal_address": {
        "city": "Sun City",
        "post_code": "12345",
        "country_code": "AD"
      },
      "contact": {
        "point": "Jens Jensen",
        "telephone_number": "876 654 321",
        "email_address": "jens.j@buyer.se"
      }
    },
    "buyer": {
      "name": "Buyer Full Name AS",
      "electronic_address": {
        "value": "DE987654321",
        "scheme_identifier": "9930"
      },
      "postal_address": {
        "city": "Moon City",
        "post_code": "12345",
        "country_code": "AD"
      }
    },
    "payment_instructions": {
      "payment_means_type_code": "30",
      "credit_transfer": [
        {
          "payment_account_identifier": "NO99991122222"
        }
      ]
    },
    "document_totals": {
      "sum_of_invoice_line_net_amount": 2145,
      "invoice_total_amount_without_vat": 2145,
      "invoice_total_amount_with_vat": 2681.25,
      "invoice_total_vat_amount": 536.25,
      "amount_due_for_payment": 2681.25
    },
    "vat_breakdown": [
      {
        "vat_category_taxable_amount": 2145,
        "vat_category_tax_amount": 536.25,
        "vat_category_code": "S",
        "vat_category_rate": 25
      }
    ],
    "invoice_line": [
      {
        "invoice_line_identifier": "12",
        "invoiced_quantity": 100,
        "invoiced_quantity_unit_of_measure_code": "Lizenzen",
        "invoice_line_net_amount": 2145,
        "price_details": {
          "item_net_price": 21.45,
          "item_price_discount": 100,
          "item_gross_price": 121.45
        },
        "invoice_line_period": {
          "invoice_line_period_start_date": "2025-02-02"
        },
        "line_vat_information": {
          "invoiced_item_vat_category_code": "S",
          "invoiced_item_vat_rate": 25
        },
        "item_information": {
          "name": "Item name"
        }
      }
    ],
    "validation_mode": "lax"
  }
}

The invoice object is a standard finaX invoice payload. The config object allows to configure PDF specific settings.

Config Options

config:
- intro_text: Introductory text to be displayed at the beginning of the PDF.
- logo: Logo to be included in the PDF.
  - type: Type of the logo file. Supported types are png, jpeg, svg and webp.
  - file: Base64 encoded string of the logo file.
- outro_text: Outro text to be displayed at the end of the PDF.
- file_name: Desired file name for the generated PDF. Defaults to invoice.pdf.
- language: Language code for the PDF content. Supported codes are de, en, and fr. Defaults to de.

When the invoice is processed by the finaX API with the above payload, a ZUGFeRD compliant PDF will be generated and returned in the response.

Set ZUGFeRD PDF Language

The language of the generated ZUGFeRD PDF can be set using the config.language field in the invoice payload.

English ZUGFeRD PDF

{
  "config": {
    "language": "en",
    "intro_text": "To whom it may concern, please find attached the invoice.",
    "outro_text": "Thank you for your business!",
    "file_name": "invoice.pdf",
  },
  "invoice": {
    "invoice_number": "33445566",
    "invoice_issue_date": "2019-08-24",
    "invoice_type_code": 380,
    "invoice_currency_code": "EUR",
    "buyer_reference": "abs1234",
    "payment_terms": "#SKONTO#TAGE=14#PROZENT=2.25#",
    "delivery_information": {
      "actual_delivery_date": "2025-10-10"
    },
    "seller": {
      "name": "Full Formal Seller Name LTD.",
      "vat_identifier": "DE-123",
      "identifier": [
        {
          "scheme_identifier": "0094",
          "value": "Full Formal Seller Name LTD."
        }
      ],
      "electronic_address": {
        "value": "DE123456789",
        "scheme_identifier": "9930"
      },
      "postal_address": {
        "city": "Sun City",
        "post_code": "12345",
        "country_code": "AD"
      },
      "contact": {
        "point": "Jens Jensen",
        "telephone_number": "876 654 321",
        "email_address": "jens.j@buyer.se"
      }
    },
    "buyer": {
      "name": "Buyer Full Name AS",
      "electronic_address": {
        "value": "DE987654321",
        "scheme_identifier": "9930"
      },
      "postal_address": {
        "city": "Moon City",
        "post_code": "12345",
        "country_code": "AD"
      }
    },
    "payment_instructions": {
      "payment_means_type_code": "30",
      "credit_transfer": [
        {
          "payment_account_identifier": "NO99991122222"
        }
      ]
    },
    "document_totals": {
      "sum_of_invoice_line_net_amount": 2145,
      "invoice_total_amount_without_vat": 2145,
      "invoice_total_amount_with_vat": 2681.25,
      "invoice_total_vat_amount": 536.25,
      "amount_due_for_payment": 2681.25
    },
    "vat_breakdown": [
      {
        "vat_category_taxable_amount": 2145,
        "vat_category_tax_amount": 536.25,
        "vat_category_code": "S",
        "vat_category_rate": 25
      }
    ],
    "invoice_line": [
      {
        "invoice_line_identifier": "12",
        "invoiced_quantity": 100,
        "invoiced_quantity_unit_of_measure_code": "Lizenzen",
        "invoice_line_net_amount": 2145,
        "price_details": {
          "item_net_price": 21.45,
          "item_price_discount": 100,
          "item_gross_price": 121.45
        },
        "invoice_line_period": {
          "invoice_line_period_start_date": "2025-02-02"
        },
        "line_vat_information": {
          "invoiced_item_vat_category_code": "S",
          "invoiced_item_vat_rate": 25
        },
        "item_information": {
          "name": "Item name"
        }
      }
    ],
    "validation_mode": "lax"
  }
}

Creating Factur-X PDFs with the X-FINAX-PROFILE Header

By default, the /v1/pdf/json endpoint generates XRechnung-compliant PDFs with the embedded XML using the XRechnung customization ID. If you want to create Factur-X/ZUGFeRD PDFs that comply with the broader EN 16931 standard instead of German-specific XRechnung requirements, use the X-FINAX-PROFILE header.

When you set X-FINAX-PROFILE: EN 16931, the API automatically:

Changes the embedded XML filename from xrechnung.xml to factur-x.xml
Updates the customization ID from urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0 to urn:cen.eu:en16931:2017
Skips German-specific validation rules (BR-DE-*)

This is useful when:

You don't need to comply with German XRechnung requirements
You're creating invoices for French recipients (Factur-X)
You want broader European EN 16931 compliance without country-specific restrictions

Example: Creating a Factur-X PDF

Create Factur-X PDF

curl -X POST "https://api.finax.dev/v1/pdf/json/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-FINAX-PROFILE: EN 16931" \
  -d '{
    "config": {
      "intro_text": "Please find your invoice attached.",
      "outro_text": "Thank you for your business!",
      "file_name": "factur-x-invoice.pdf",
      "language": "en"
    },
    "invoice": {
      "invoice_number": "33445566",
      "invoice_issue_date": "2019-08-24",
      "invoice_type_code": 380,
      "invoice_currency_code": "EUR",
      "buyer_reference": "abs1234",
      "payment_terms": "#SKONTO#TAGE=14#PROZENT=2.25#",
      "delivery_information": {
        "actual_delivery_date": "2025-10-10"
      },
      "seller": {
        "name": "Full Formal Seller Name LTD.",
        "vat_identifier": "DE-123",
        "identifier": [
          {
            "scheme_identifier": "0094",
            "value": "Full Formal Seller Name LTD."
          }
        ],
        "electronic_address": {
          "value": "DE123456789",
          "scheme_identifier": "9930"
        },
        "postal_address": {
          "city": "Sun City",
          "post_code": "12345",
          "country_code": "AD"
        },
        "contact": {
          "point": "Jens Jensen",
          "telephone_number": "876 654 321",
          "email_address": "jens.j@buyer.se"
        }
      },
      "buyer": {
        "name": "Buyer Full Name AS",
        "electronic_address": {
          "value": "DE987654321",
          "scheme_identifier": "9930"
        },
        "postal_address": {
          "city": "Moon City",
          "post_code": "12345",
          "country_code": "AD"
        }
      },
      "payment_instructions": {
        "payment_means_type_code": "30",
        "credit_transfer": [
          {
            "payment_account_identifier": "NO99991122222"
          }
        ]
      },
      "document_totals": {
        "sum_of_invoice_line_net_amount": 2145,
        "invoice_total_amount_without_vat": 2145,
        "invoice_total_amount_with_vat": 2681.25,
        "invoice_total_vat_amount": 536.25,
        "amount_due_for_payment": 2681.25
      },
      "vat_breakdown": [
        {
          "vat_category_taxable_amount": 2145,
          "vat_category_tax_amount": 536.25,
          "vat_category_code": "S",
          "vat_category_rate": 25
        }
      ],
      "invoice_line": [
        {
          "invoice_line_identifier": "12",
          "invoiced_quantity": 100,
          "invoiced_quantity_unit_of_measure_code": "Lizenzen",
          "invoice_line_net_amount": 2145,
          "price_details": {
            "item_net_price": 21.45,
            "item_price_discount": 100,
            "item_gross_price": 121.45
          },
          "invoice_line_period": {
            "invoice_line_period_start_date": "2025-02-02"
          },
          "line_vat_information": {
            "invoiced_item_vat_category_code": "S",
            "invoiced_item_vat_rate": 25
          },
          "item_information": {
            "name": "Item name"
          }
        }
      ],
      "validation_mode": "lax"
    }
  }' -o factur-x-invoice.pdf

The resulting PDF will contain a factur-x.xml attachment with the EN 16931 customization ID, making it compliant with the Factur-X standard.

Credit Notes

Learn how to create credit notes for refunds and reversals using the finaX e-invoicing API.

Custom PDFs

Use your own PDF design to create ZUGFeRD / Factur-X invoices.