> ## Documentation Index
> Fetch the complete documentation index at: https://invopop-singapore.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# XRechnung Guide

> Generate compliant invoices in Germany (X-Rechnung).

## Introduction

**XRechnung** is Germany’s official standard for electronic invoices in public procurement (called *E-Rechnungen*), though it is also used for B2B transactions. It’s part of the implementation of the EU directive `2014/55/EU`, which requires all contracting authorities in the EU to accept electronic invoices in a structured XML file. It can be implemented using two different *syntaxes*, CII and UBL. They both contain the same information, but have different field names.

<Tip>
  When referring to syntaxes, it is important to note that X-Rechnung and 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](https://unece.org/trade/documents/2023/10/executive-guide-einvoicing-cross-industry-invoice)) and OpenOasis Universal Business Language ([UBL](https://docs.oasis-open.org/ubl/UBL-2.1.html)).
</Tip>

## Prerequisites

To convert invoices to XRechnung format, ensure you have:

* A valid API key and a basic understanding of the [workflow engine](/guides/features/workflows) and [API](api-ref/introduction).
* An invoice with:
  * Supplier details (company name and required identities). Check the [German](https://docs.gobl.org/regimes/de) regimes for specifics.
  * Line items with name, price, and applicable taxes.

## XRechnung Setup

To issue XRechnung invoices, follow these instructions in the [Invopop Console](https://console.invopop.com):

<Steps>
  <Step title="Connect the OASIS UBL app">
    1. Navigate to **Configuration** → **Apps**.
    2. Locate **OASIS UBL** in the app discovery list.
    3. Click **Connect** to activate.

    No additional configuration is needed.
  </Step>

  <Step title="Configure invoice workflow">
    <Tabs>
      <Tab title="Template">
        <Card iconType="duotone" title="XRechnung invoice workflow" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=de-xrechnung" cta="Add to my workspace">
          This workflow will generate an XRechnung UBL document.
        </Card>
      </Tab>

      <Tab title="Code">
        Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view.

        ```json Example X-Rechnung workflow with states theme={"system"}
        {
            "name": "XRechnung invoice",
            "description": "Issue XRechnung invoices in Germany (B2G)",
            "schema": "bill/invoice",
            "steps": [
                {
                    "id": "bd7eb640-abd0-11ef-a013-91c68ca9f44b",
                    "name": "Set State",
                    "provider": "silo.state",
                    "summary": "Set state to `processing`{.state .processing}",
                    "config": {
                        "state": "processing"
                    }
                },
                {
                    "id": "58fb4ce0-6626-11f0-b9ab-1bbe1fa4398c",
                    "name": "Sign Envelope",
                    "provider": "silo.close"
                },
                {
                    "id": "66c0eb20-8efb-11f0-825d-d9d5f5eb9a66",
                    "name": "Generate UBL Document",
                    "provider": "ubl.generate",
                    "summary": "XRechnung UBL Invoice V2.0",
                    "config": {
                        "doc_type": "xrechnung-invoice-v2",
                        "private": false
                    }
                },
                {
                    "id": "56bda1e0-8ef7-11f0-aa0e-dd7c69b95f3c",
                    "name": "Generate PDF",
                    "provider": "pdf",
                    "summary": "English - A4",
                    "config": {
                        "date_format": "%Y-%m-%d",
                        "layout": "A4",
                        "locale": "en",
                        "logo_height": 40,
                        "scripting": false
                    }
                },
                {
                    "id": "c6192a60-abd0-11ef-a013-91c68ca9f44b",
                    "name": "Set State",
                    "provider": "silo.state",
                    "summary": "Set state to `sent`{.state .sent}",
                    "config": {
                        "state": "sent"
                    }
                }
            ],
            "rescue": [
                {
                    "id": "c94982c0-abd0-11ef-a013-91c68ca9f44b",
                    "name": "Set State",
                    "provider": "silo.state",
                    "summary": "Set state to `error`{.state .error}",
                    "config": {
                        "state": "error"
                    }
                }
            ]
        }
        ```
      </Tab>

      <Tab title="Build from scratch">
        First, review our [workflows guide](/guides/features/workflows) to understand the basics.

        In [Console](https://console.invopop.com) create a new workflow and select [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) 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. **Generate UBL Document**: In "Invoice Output Document Type" select `XRechnung UBL Invoice v2.0`. It's also possible to use the **Generate UN/CEFACT CII Invoice** step selecting `XRechnung V3` as both UBL and CII are valid formats for XRechnung.
        4. **Set State** - Select `Sent`.

        Finally, in the "Error Handling" area, add **Set State** and select `Error`.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Running

<Note>
  In your invoice data, make sure to include the [XRechnung addon](https://docs.gobl.org/addons/de-xrechnung-v3) and state the regime as `DE`.
</Note>

Invopop uses the [GOBL](https://gobl.org) library to process conversions. GOBL's implementation of XRechnung validates [national business rules](https://www.xoev.de/sixcms/media.php/13/XRechnung-EnglishSummary-v220-final.pdf) in addition to the rules defined in `EN 16931-1`.

Some example invoices are provided below, along with an example workflow to send the invoices to. We also recommend using the [GOBL Builder](https://build.gobl.org) to create your own invoices.

Be sure to set the `regime` field to `DE` in your invoices and the [XRechnung](https://docs.gobl.org/addons/de-xrechnung-v3) addon. This will add extra validations to ensure the document is compliant with the standard.

## Sample Invoices

<AccordionGroup>
  <Accordion title="XRechnung B2B Invoice">
    ```json XRechnung B2B Invoice theme={"system"}
    {
        "$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"
        }
    }
    ```
  </Accordion>
</AccordionGroup>

You can now generate invoices in the XRechnung format via the API or console. For more details, visit the [GOBL docs](https://docs.gobl.org) or contact [Invopop Support](mailto:support@invopop.com).

## FAQ

<AccordionGroup>
  <Accordion title="Which XRechnung 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.
  </Accordion>
</AccordionGroup>