Guides
Custom PDFs
Use your own PDF design to create ZUGFeRD / Factur-X invoices.
The finaX e-invoicing API allows you to use your own PDF design to create ZUGFeRD / Factur-X compliant invoices. This is useful when you want to maintain your existing invoice template while adding e-invoicing capabilities.
Overview
The /v1/pdf/merge/ endpoint combines your custom PDF/A-3 file with CII XML to create a valid ZUGFeRD XRechnung or Factur-X invoice.
Your PDF must be PDF/A-3 compliant. finaX validates PDF/A compliance before merging. Standard PDFs will be rejected.
Requirements
- PDF/A-3 file: Your invoice PDF must be PDF/A-3 compliant
- CII XML file: A valid Cross-Industry Invoice (CII) XML according to XRechnung specification.
Creating the CII XML
Generate the CII XML using the finaX /v1/xml/cii/ endpoint:
Generate CII XML
curl -X POST "https://api.finax.dev/v1/xml/cii/" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"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#",
"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": "H87",
"invoice_line_net_amount": 2145,
"price_details": {
"item_net_price": 21.45,
"item_price_discount": 100,
"item_gross_price": 121.45
},
"line_vat_information": {
"invoiced_item_vat_category_code": "S",
"invoiced_item_vat_rate": 25
},
"item_information": {
"name": "Item name"
}
}
]
}' -o invoice.xml
Merging PDF and XML
Once you have both files, use the merge endpoint:
Merge PDF and XML
curl -X POST "https://api.finax.dev/v1/pdf/merge/" \
-H "X-API-Key: YOUR_API_KEY" \
-F "pdf_file=@your-invoice.pdf" \
-F "xml_file=@invoice.xml" \
-o zugferd-invoice.pdf
The response is a ZUGFeRD compliant PDF containing the embedded xrechnung.xml file.
When to Use Custom PDFs
The merge endpoint is ideal when:
- You have an existing invoice design you want to keep
- Your invoices are generated by external systems (ERP, accounting software)
- You need pixel-perfect control over the PDF appearance
- You're migrating an existing invoicing system to e-invoicing
For simpler use cases where you don't need custom designs, consider the /v1/pdf/json/ endpoint which generates both the PDF and XML from a single JSON payload.