Germany and France · XInvoice Guide

🇩🇪 🇫🇷 Issue invoices in Germany (X-Rechnung & ZUGFeRD) and France (Factur-X).

Introduction

XInvoice covers the German and French electronic invoice standards. The integration is the same for both countries. The supported standards are:

• X-Rechnung: one of the two standards used in Germany. It consists on an XML file. It can be implemented using two different syntaxes, CII and UBL. They both contain the same information, but include different field names.
• ZUGFeRD: the other standard used in Germany. It a hybrid format that consists on a PDF document with an embedded X-Rechnung file. The only supported syntax for this case is CII.
• Factur-X: the standard used in France. It consists on a PDF document with an embedded XML file. It is worth noting that ZUGFeRD and Factur-X are a joint project between Germany and France, and their content is identical.

When referring to syntaxes, it is important to note that X-Rechnung, ZUGFeRD and Factur-X are all semantic data models. What this means is that they define the data that must be present in the invoice, but not the actual format of the data or the explicit name of the fields.

To implement the semantic models, there are two syntaxes approved by the EU: UN/CEFACT Cross Industry Invoice (CII) and OpenOasis Universal Business Language (UBL).

Prerequisites

To convert invoices to XInvoice format, ensure you have:

• A valid API key and a basic understanding of the workflow engine and API.
• An invoice with:
  • Supplier details (company name and required identities). Check the German and French regimes for specifics.
  • Line items with name, price, and applicable taxes.

Setup

To issue invoices, follow these instructions in the Invopop Console:

1. Connect the XInvoice app

   1. Navigate to Configuration → Apps.
   2. Locate XInvoice France/Germany in the app discovery list.
   3. Click Connect to activate.

   No additional configuration is needed.

2. Configure invoice workflow

   Template

   XInvoice workflow

   This workflow will generate an XInvoice XML document and embed it into a PDF.

   Add to my workspace

   XInvoice workflow

   This workflow will generate an XInvoice XML document and embed it into a PDF.

   Add to my workspace

   Copy and paste into a new Empty Invoice workflow code view.

   Example X-Rechnung workflow with states

   {
     "name": "X-Rechnung issue invoice",
     "description": "Issue B2G invoices in Germany",
     "schema": "bill/invoice",
     "steps": [
       {
         "id": "bd7eb640-abd0-11ef-a013-91c68ca9f44b",
         "name": "Set State",
         "config": {
             "state": "processing"
         },
         "summary": "Set state to `processing`{.state .processing}",
         "provider": "silo.state"
       },
       {
         "id": "c37c3860-abd0-11ef-a013-91c68ca9f44b",
         "name": "Sign Envelope",
         "provider": "silo.close"
       },
       {
         "id": "78504b10-abd0-11ef-a013-91c68ca9f44b",
         "name": "Convert to XRechnung/Factur-X",
         "provider": "xinvoice.convert"
       },
       {
         "id": "7ad436d0-abd0-11ef-a013-91c68ca9f44b",
         "name": "Generate PDF",
         "config": {
             "locale": "en",
             "date_format": "%Y-%m-%d",
             "logo_height": 40
         },
         "summary": "English",
         "provider": "pdf"
       },
       {
         "id": "c6192a60-abd0-11ef-a013-91c68ca9f44b",
         "name": "Set State",
         "config": {
             "state": "sent"
         },
         "summary": "Set state to `sent`{.state .sent}",
         "provider": "silo.state"
       }
     ],
     "rescue": [
       {
           "id": "c94982c0-abd0-11ef-a013-91c68ca9f44b",
           "name": "Set State",
           "config": {
               "state": "error"
           },
           "summary": "Set state to `error`{.state .error}",
           "provider": "silo.state"
       }
     ]
   }
   

   First, review our workflows guide to understand the basics.

   In Console create a new workflow and select Empty Invoice workflow in the template selector, then add the essential steps:

   1. Set State - Select Processing
   2. Sign Envelope: The envelope must be signed before processing.
   3. Convert to XRechnung/Factur-X: Generates the XInvoice XML document.
   4. Generate PDF: For ZUGFeRD and Factur-X formats, this step creates the PDF with the embedded XML.
   5. Set State - Select Sent.

   Finally, in the “Error Handling” area, add Set State and select Error.

Running

Invopop uses the GOBL library to process conversions. Some example invoices are provided below, along with an example workflow to send the invoices to. We also recommend using the GOBL Builder to create your own invoices.

Be sure to set the regime field to DE or FR in your invoices. This will add some extra validations to ensure the document is compliant. If you plan to issue X-Rechnung invoices, we also recommend using the X-Rechnung addon in the invoice file (see example below), to add further validation.

Sample Invoices

Regular B2B Invoice

B2B Invoice

{
    "$schema": "https://gobl.org/draft-0/bill/invoice",
    "$regime": "DE",
    "$addons": [
        "eu-en16931-v2017",
        "de-xrechnung-v3"
    ],
    "uuid": "3aea7b56-59d8-4beb-90bd-f8f280d852a0",
    "type": "standard",
    "series": "SAMPLE",
    "code": "001",
    "issue_date": "2022-02-01",
    "currency": "EUR",
    "tax": {
        "ext": {
            "untdid-document-type": "380"
        }
    },
    "supplier": {
        "name": "Provide One GmbH",
        "tax_id": {
            "country": "DE",
            "code": "111111125"
        },
        "addresses": [
            {
                "num": "16",
                "street": "Dietmar-Hopp-Allee",
                "locality": "Walldorf",
                "code": "69190",
                "country": "DE"
            }
        ],
        "emails": [
            {
                "addr": "[e-mail]"
            }
        ]
    },
    "customer": {
        "name": "Sample Consumer",
        "tax_id": {
            "country": "DE",
            "code": "282741168"
        },
        "addresses": [
            {
                "num": "25",
                "street": "Werner-Heisenberg-Allee",
                "locality": "München",
                "code": "80939"
            }
        ],
        "emails": [
            {
                "addr": "[e-mail]"
            }
        ]
    },
    "lines": [
        {
            "i": 1,
            "quantity": "20",
            "item": {
                "name": "Development services",
                "price": "90.00",
                "unit": "h"
            },
            "sum": "1800.00",
            "discounts": [
                {
                    "reason": "Special discount",
                    "percent": "10%",
                    "amount": "180.00"
                }
            ],
            "taxes": [
                {
                    "cat": "VAT",
                    "rate": "standard",
                    "percent": "19%",
                    "ext": {
                        "untdid-tax-category": "S"
                    }
                }
            ],
            "total": "1620.00"
        }
    ],
    "payment": {
        "instructions": {
            "key": "credit-transfer+sepa",
            "credit_transfer": [
                {
                    "iban": "DE89370400440532013000",
                    "name": "Random Bank Co."
                }
            ],
            "ext": {
                "untdid-payment-means": "58"
            }
        }
    },
    "totals": {
        "sum": "1620.00",
        "total": "1620.00",
        "taxes": {
            "categories": [
                {
                    "code": "VAT",
                    "rates": [
                        {
                            "key": "standard",
                            "ext": {
                                "untdid-tax-category": "S"
                            },
                            "base": "1620.00",
                            "percent": "19%",
                            "amount": "307.80"
                        }
                    ],
                    "amount": "307.80"
                }
            ],
            "sum": "307.80"
        },
        "tax": "307.80",
        "total_with_tax": "1927.80",
        "payable": "1927.80"
    }
}

Regular B2C Invoice

B2C Invoice

{
    "$schema": "https://gobl.org/draft-0/bill/invoice",
    "$regime": "DE",
    "$addons": [
        "eu-en16931-v2017",
    ],
    "$tags": [
        "simplified"
    ],
    "uuid": "3aea7b56-59d8-4beb-90bd-f8f280d852a0",
    "type": "standard",
    "series": "SAMPLE",
    "code": "001",
    "issue_date": "2022-02-01",
    "currency": "EUR",
    "supplier": {
        "name": "Provide One GmbH",
        "tax_id": {
            "country": "DE"
        },
        "addresses": [
            {
                "num": "16",
                "street": "Dietmar-Hopp-Allee",
                "locality": "Walldorf",
                "code": "69190",
                "country": "DE"
            }
        ],
        "emails": [
            {
                "addr": "[e-mail]"
            }
        ]
    },
    "lines": [
        {
            "i": 1,
            "quantity": "20",
            "item": {
                "name": "Development services",
                "price": "90.00",
                "unit": "h"
            },
            "sum": "1800.00",
            "discounts": [
                {
                    "reason": "Special discount",
                    "percent": "10%",
                    "amount": "180.00"
                }
            ],
            "taxes": [
                {
                    "cat": "VAT",
                    "rate": "standard",
                    "percent": "19%"
                }
            ],
            "total": "1620.00"
        }
    ],
    "totals": {
        "sum": "1620.00",
        "total": "1620.00",
        "taxes": {
            "categories": [
                {
                    "code": "VAT",
                    "rates": [
                        {
                            "key": "standard",
                            "base": "1620.00",
                            "percent": "19%",
                            "amount": "307.80"
                        }
                    ],
                    "amount": "307.80"
                }
            ],
            "sum": "307.80"
        },
        "tax": "307.80",
        "total_with_tax": "1927.80",
        "payable": "1927.80"
    }
}

B2B Invoice with Additional Fields

B2B Invoice with additional fields

{
    "$schema": "https://gobl.org/draft-0/bill/invoice",
    "$regime": "DE",
    "$addons": [
        "eu-en16931-v2017"
    ],
    "uuid": "019231f1-9128-71fc-b0e2-820af3036d1b",
    "type": "standard",
    "series": "SAMPLE",
    "code": "001",
    "issue_date": "2024-02-13",
    "currency": "EUR",
    "supplier": {
        "name": "Provide One GmbH",
        "tax_id": {
            "country": "DE",
            "code": "111111125"
        },
        "people": [
            {
                "name": {
                    "given": "John",
                    "surname": "Doe"
                }
            }
        ],
        "addresses": [
            {
                "num": "16",
                "street": "Dietmar-Hopp-Allee",
                "locality": "Walldorf",
                "code": "69190",
                "country": "DE"
            }
        ],
        "emails": [
            {
                "addr": "[e-mail]"
            }
        ],
        "telephones": [
            {
                "num": "[phone]"
            }
        ]
    },
    "customer": {
        "name": "Sample Consumer",
        "tax_id": {
            "country": "DE",
            "code": "282741168"
        },
        "addresses": [
            {
                "num": "25",
                "street": "Werner-Heisenberg-Allee",
                "locality": "München",
                "code": "80939",
                "country": "DE"
            }
        ],
        "emails": [
            {
                "addr": "[e-mail]"
            }
        ]
    },
    "lines": [
        {
            "i": 1,
            "quantity": "20",
            "item": {
                "name": "Development services",
                "price": "90.00",
                "unit": "h"
            },
            "sum": "1800.00",
            "taxes": [
                {
                    "cat": "VAT",
                    "rate": "standard",
                    "percent": "19%"
                }
            ],
            "total": "1800.00"
        }
    ],
    "discounts": [
        {
            "i": 1,
            "amount": "10.00",
            "taxes": [
            {
                "cat": "VAT",
                "rate": "standard",
                "percent": "25%"
            }
            ],
            "reason": "Promotion discount",
            "ext": {
            "untdid-allowance": "88"
            }
        }
    ],
    "charges": [
        {
            "i": 1,
            "amount": "11.00",
            "taxes": [
                {
                    "cat": "VAT",
                    "rate": "standard",
                    "percent": "25%"
                }
            ],
            "reason": "Freight",
            "ext": {
                "untdid-charge": "88"
            }
        }
        ],
    "ordering": {
        "code": "PO4711",
        "period": {
            "start": "2013-03-10",
            "end": "2013-04-10"
        },
        "contracts": [
            {
            "code": "2013-05"
            }
        ],
        "receiving": [
            {
            "code": "3544"
            }
        ],
        "despatch": [
            {
            "code": "5433"
            }
        ]
    },
    "payment": {
        "payee": {
            "name": "Ebeneser Scrooge AS",
            "identities": [
            {
                "label": "CompanyID",
                "code": "989823401"
            },
            {
                "label": "0088",
                "code": "2298740918237"
            }
            ]
        },
        "terms": {
            "due_dates": [
            {
                "date": "2013-07-20",
                "amount": "2142.00",
                "percent": "100%"
            }
            ],
            "notes": "2 % discount if paid within 2 days\n            Penalty percentage 10% from due date"
        },
        "instructions": {
            "key": "credit-transfer",
            "ref": "0003434323213231",
            "ext": {
                "untdid-payment-means": "30"
            },
            "credit_transfer": [
            {
                "iban": "NO9386011117947",
                "bic": "DNBANOKK"
            }
            ],
            "direct_debit": {
                "creditor": "987654321",
                "account": "DE89370400440532013000",
                "ref": "1234567890"
            },
            "card": {
                "last4": "1234",
                "holder": "John Doe"
            }
        }
    },
    "delivery": {
        "receiver": {
            "addresses": [
                {
                    "street": "Deliverystreet 2",
                    "street_extra": "Side door",
                    "locality": "DeliveryCity",
                    "region": "RegionD",
                    "code": "523427",
                    "country": "NO"
                }
            ]
        },
        "identities": [
            {
                "label": "0088",
                "code": "6754238987643"
            }
        ],
        "date": "2024-02-10"
    },
    "tax": {
        "ext": {
            "untdid-document-type": "380"
        }
    },
    "totals": {
        "sum": "1800.00",
        "total": "1800.00",
        "taxes": {
            "categories": [
                {
                    "code": "VAT",
                    "rates": [
                        {
                            "key": "standard",
                            "base": "1800.00",
                            "percent": "19%",
                            "amount": "342.00"
                        }
                    ],
                    "amount": "342.00"
                }
            ],
            "sum": "342.00"
        },
        "tax": "342.00",
        "total_with_tax": "2142.00",
        "payable": "2142.00"
    }
}

You can now generate invoices in the XInvoice format via the API or console. For more details, visit the GOBL docs and XInvoice repo, or contact Invopop Support.

FAQ

Which X-Rechnung syntax should I choose, UBL or CII?

Both syntaxes are equally valid and contain the same information, so in the majority of cases the choice has no consequences.

If you plan on sending Invoices through the PEPPOL network, we recommend using UBL as it is the supported format. If you plan on also issuing invoices in ZUGFeRD or Factur-X, it might be more convenient to use CII, as it is the syntax also supported by ZUGFeRD and Factur-X.

How can I view an XML attached to a PDF?

For ZUGFeRD and Factur-X PDFs, the XML file is embedded within the PDF itself. To extract and view it, you can use the Attachments section in Adobe Acrobat Reader.

Alternatively, you can use specialized tools like the SysTools PDF Extractor to extract the XML file.

Assistant

Responses are generated using AI and may contain mistakes.