Guides
ZUGFeRD Profiles
Learn how to create ZUGFeRD/Factur-X invoices with different conformance profiles using the finaX API.
The finaX e-invoicing API supports multiple ZUGFeRD/Factur-X conformance profiles. This guide explains how to choose between the XRechnung profile (default) and the EN 16931 profile.
Profile Overview
| Profile | Validation | Use Case |
|---|---|---|
| XRechnung | Strict (includes German BR-DE-* rules) | German public sector, domestic B2B |
| EN 16931 | Relaxed (EN16931 core rules only) | International trade, non-German recipients |
The EN 16931 profile applies only the European standard validation rules. No country-specific rules (like German BR-DE-*) are enforced, making it more flexible for international invoicing.
Generating CII XML
Use the X-FINAX-CIUS header with the /v1/xml/cii/ endpoint to control which profile the generated CII XML conforms to.
XRechnung Profile (Default)
When no header is specified, the API generates XRechnung-compliant CII XML:
XRechnung CII (Default)
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#",
"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 xrechnung-invoice.xml
EN 16931 Profile
To generate EN 16931 compliant CII, set the X-FINAX-CIUS header to Factur-X EN 16931:
EN 16931 CII
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 EN 16931" \
-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#",
"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 facturx-invoice.xml
Creating ZUGFeRD PDFs with Custom Templates
When using the /v1/pdf/merge/ endpoint to combine your own PDF/A-3 with CII XML, use the X-FINAX-PROFILE header to set the ZUGFeRD conformance level.
XRechnung Profile (Default)
Merge with XRechnung Profile
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=@xrechnung-invoice.xml" \
-o zugferd-xrechnung.pdf
EN 16931 Profile
To create a ZUGFeRD/EN 16931 compliant PDF, set the X-FINAX-PROFILE header to EN 16931:
Merge with EN 16931 Profile
curl -X POST "https://api.finax.dev/v1/pdf/merge/" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-FINAX-PROFILE: EN 16931" \
-F "pdf_file=@your-invoice.pdf" \
-F "xml_file=@facturx-invoice.xml" \
-o zugferd-en16931.pdf
Complete Workflow Example
Here's a complete example showing how to create a ZUGFeRD EN 16931 invoice using your own PDF template:
Step 1: Generate EN16931 CII XML
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" \
-H "X-FINAX-CIUS: EN 16931" \
-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#",
"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 en16931-invoice.xml
Step 2: Merge with PDF using EN 16931 Profile
Merge PDF and XML
curl -X POST "https://api.finax.dev/v1/pdf/merge/" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-FINAX-PROFILE: EN 16931" \
-F "pdf_file=@your-invoice.pdf" \
-F "xml_file=@en16931-invoice.xml" \
-o final-zugferd-en16931.pdf
When to Use Each Profile
Use XRechnung when:
- Invoicing German public sector entities
- Your buyer requires XRechnung compliance
- You need to comply with German-specific business rules (BR-DE-*)
Use EN 16931 when:
- Trading with non-German European partners
- Your invoice data doesn't meet German-specific requirements
- Creating Factur-X invoices for French recipients
Header Reference
| Header | Endpoint | Values | Default |
|---|---|---|---|
X-FINAX-CIUS | /v1/xml/cii/ | XRechnung, EN 16931 | XRechnung |
X-FINAX-PROFILE | /v1/pdf/merge/ | XRECHNUNG, EN 16931 | XRECHNUNG |