Germany and France · XInvoice Guide

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:

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

XInvoice workflow

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

XInvoice workflow

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

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:

Set State - Select Processing
Sign Envelope: The envelope must be signed before processing.
Convert to XRechnung/Factur-X: Generates the XInvoice XML document.
Generate PDF: For ZUGFeRD and Factur-X formats, this step creates the PDF with the embedded XML.
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": "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"
    }
}

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": "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"
    }
}

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": "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 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?

How can I view an XML attached to a PDF?

Getting Started

Use Cases

Feature Guides

Country Guides

Integrations

Germany and France · XInvoice Guide

Introduction

Prerequisites

Setup

XInvoice workflow

XInvoice workflow

Running

Sample Invoices

FAQ

Getting Started

Use Cases

Feature Guides

Country Guides

Integrations

​Introduction

​Prerequisites

​Setup

XInvoice workflow

XInvoice workflow

​Running

​Sample Invoices

​FAQ

Introduction

Prerequisites

Setup

Running

Sample Invoices

FAQ