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-2 or PDF/A-3 file with CII XML to create a valid ZUGFeRD XRechnung or Factur-X invoice.

Your PDF must be PDF/A-2 or PDF/A-3 compliant. finaX validates PDF/A compliance before merging. Standard PDFs will be rejected.

Requirements

PDF/A file: Your invoice PDF must be PDF/A-2 or PDF/A-3 compliant
CII XML file: A valid Cross-Industry Invoice (CII) XML for the profile you want to create.

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

Creating a ZUGFeRD Extended Invoice

To create an invoice using the ZUGFeRD / Factur-X Extended profile, first generate Extended CII XML with the /v1/xml/cii/ endpoint. Set X-FINAX-CIUS to Factur-X EXTENDED when sending invoice data that contains Extended fields.

Currently, the finaX JSON API supports these Extended fields:

BT-X-13: Item classification name, provided as invoice_line[].item_information.classification_identifier[].name
BG-X-44: Payment discount terms, provided as payment_discount_terms

Other ZUGFeRD Extended fields are not yet supported by the JSON-to-CII endpoint. Contact us if you need additional fields supported.

Generate Extended CII XML

curl -X POST "https://api.finax.dev/v1/xml/cii/" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "X-FINAX-CIUS: Factur-X EXTENDED" \
    -d '{
        "invoice_number": "33445566",
        "invoice_issue_date": "2019-08-24",
        "invoice_type_code": 380,
        "invoice_currency_code": "EUR",
        "value_added_tax_point_date": "2019-08-24",
        "buyer_reference": "abs1234",
        "payment_terms": "#SKONTO#TAGE=14#PROZENT=2.25#",
        "invoice_note": [
            {
                "invoice_note": "Please note our new phone number 33 44 55 66",
                "invoice_note_subject_code": "INV"
            }
        ],
        "seller": {
            "name": "Full Formal Seller Name LTD.",
            "trading_name": "Seller Business Name AS",
            "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",
            "identifier": {
                "scheme_identifier": "0094",
                "value": "SE8765456787"
            },
            "legal_registration_identifier": {
                "scheme_identifier": "0094",
                "value": "5560104525"
            },
            "vat_identifier": "SE8765456787",
            "electronic_address": {
                "value": "DE987654321",
                "scheme_identifier": "9930"
            },
            "postal_address": {
                "city": "Moon City",
                "post_code": "12345",
                "country_code": "AD"
            },
            "contact": {
                "point": "Jens Jensen",
                "telephone_number": "876 654 321",
                "email_address": "jens.j@buyer.se"
            }
        },
        "payment_instructions": {
            "payment_means_type_code": "30",
            "payment_means_text": "Credit transfer",
            "remittance_information": "432948234234234",
            "credit_transfer": [
                {
                    "payment_account_identifier": "NO99991122222",
                    "payment_account_name": "Payment Account",
                    "payment_service_provider_identifier": "SSKMDEMMXXX"
                }
            ]
        },
        "document_totals": {
            "sum_of_invoice_line_net_amount": 2145,
            "sum_of_allowances_on_document_level": 0,
            "sum_of_charges_on_document_level": 0,
            "invoice_total_amount_without_vat": 2145,
            "invoice_total_vat_amount": 536.25,
            "invoice_total_vat_amount_in_accounting_currency": 536.25,
            "invoice_total_amount_with_vat": 2681.25,
            "paid_amount": 1000,
            "rounding_amount": 0,
            "amount_due_for_payment": 1681.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",
                "invoice_line_note": "New article number 12345",
                "invoice_line_object_identifier": {
                    "scheme_identifier": "AAA",
                    "value": "AB1345"
                },
                "invoiced_quantity": 100,
                "invoiced_quantity_unit_of_measure_code": "H87",
                "invoice_line_net_amount": 2145,
                "referenced_purchase_order_line_reference": "3",
                "invoice_line_buyer_accounting_reference": "1287:65464",
                "invoice_line_period": {
                    "invoice_line_period_start_date": "2019-08-24",
                    "invoice_line_period_end_date": "2019-08-24"
                },
                "invoice_line_allowances": {
                    "amount": 200,
                    "base_amount": 1000,
                    "percentage": 20,
                    "reason": "Discount",
                    "reason_code": "95"
                },
                "invoice_line_charges": {
                    "amount": 200,
                    "base_amount": 1000,
                    "percentage": 20,
                    "reason": "Overtime",
                    "reason_code": "ABD"
                },
                "price_details": {
                    "item_net_price": 21.45,
                    "item_price_discount": 100,
                    "item_gross_price": 121.45,
                    "item_price_base_quantity": 1,
                    "item_price_base_quantity_unit_of_measure_code": "H87"
                },
                "line_vat_information": {
                    "invoiced_item_vat_category_code": "S",
                    "invoiced_item_vat_rate": 25
                },
                "item_information": {
                    "name": "Item name",
                    "description": "Long description of the item on the invoice line",
                    "sellers_identifier": "9873242",
                    "buyers_identifier": "123455",
                    "standard_identifier": {
                        "scheme_identifier": "0002",
                        "value": "string"
                    },
                    "classification_identifier": [
                        {
                            "scheme_identifier": "AA",
                            "value": "string"
                        }
                    ],
                    "country_of_origin": "DE",
                    "item_attributes": [
                        {
                            "name": "Color",
                            "value": "Black"
                        }
                    ]
                }
            }
        ],
        "payment_discount_terms": {
            "basis_period_measure": "10",
            "unit_code": "DAY",
            "basis_amount": 1000,
            "calculation_percent": 2,
            "actual_discount_amount": 20
        }
    }' -o extended-invoice.xml

Merging PDF and XML

Once you have both files, use the merge endpoint. The X-FINAX-PROFILE header defaults to XRECHNUNG when omitted:

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.

For an Extended invoice, set X-FINAX-PROFILE to EXTENDED and use the Extended CII XML generated above:

Merge with Extended Profile

curl -X POST "https://api.finax.dev/v1/pdf/merge/" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "X-FINAX-PROFILE: EXTENDED" \
    -F "pdf_file=@your-invoice.pdf" \
    -F "xml_file=@extended-invoice.xml" \
    -o zugferd-extended.pdf

The selected merge profile must match the profile of the CII XML.

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.

ZUGFeRD PDFs

How to create ZUGFeRD compliant PDFs with finaX.

ZUGFeRD Profiles

Learn how to create ZUGFeRD/Factur-X invoices with different conformance profiles using the finaX API.