Germany & France - X-Invoice

Introduction

X-Invoice 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 X-Invoice 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:

Connect the XInvoice app

Navigate to Configuration > Apps.
Locate XInvoice France/Germany in the app discovery list.
Click Connect to activate.

No additional configuration is needed.

Configure invoice workflow

First, review our workflows guide to understand the basics.

Create an Invoices workflow with these essential steps:

Sign Envelope: The envelope must be signed before processing. This can also be done in the Add Sequential Code step, which handles the invoice number.
Convert to X-Invoice: Generates the X-Invoice XML document.
Generate PDF: For ZUGFeRD and Factur-X formats, this step creates the PDF with the embedded XML.

Copy and paste the following JSON while editing a Workflow in “developer” mode. This example adds support for setting states on silo entries, which we strongly recommend.

Example X-Rechnung Workflow with States
{
    "name": "X-Rechnung",
    "description": "Convert to X-Rechnung",
    "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",
            "next": [
                {
                    "status": "KO",
                    "step_id": "c94982c0-abd0-11ef-a013-91c68ca9f44b"
                }
            ],
            "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",
            "next": [
                {
                    "stop": true,
                    "status": "NA"
                }
            ],
            "config": {
                "state": "sent"
            },
            "summary": "Set state to `sent`{.state .sent}",
            "provider": "silo.state"
        },
        {
            "id": "c94982c0-abd0-11ef-a013-91c68ca9f44b",
            "name": "Set State",
            "config": {
                "state": "error"
            },
            "summary": "Set state to `error`{.state .error}",
            "provider": "silo.state"
        }
    ]
}

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

{
    "$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": "billing@example.com"
            }
        ]
    },
    "customer": {
        "name": "Sample Consumer",
        "tax_id": {
            "country": "DE",
            "code": "282741168"
        },
        "addresses": [
            {
                "num": "25",
                "street": "Werner-Heisenberg-Allee",
                "locality": "München",
                "code": "80939"
            }
        ],
        "emails": [
            {
                "addr": "email@sample.com"
            }
        ]
    },
    "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"
    }
}

{
    "$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": "billing@example.com"
            }
        ]
    },
    "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"
    }
}

{
    "$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": "billing@example.com"
            }
        ],
        "telephones": [
            {
                "num": "+49100200300"
            }
        ]
    },
    "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": "email@sample.com"
            }
        ]
    },
    "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 X-Invoice format via the API or console. For more details, visit the GOBL docs and X-Invoice repo, or contact Invopop Support.

Introduction

API

Guides

Germany & France - X-Invoice

Introduction

Prerequisites

Setup

Running

Sample Invoices

FAQ

Introduction

API

Guides

​Introduction

​Prerequisites

​Setup

​Running

​Sample Invoices

​FAQ

Introduction

Prerequisites

Setup

Running

Sample Invoices

FAQ