> ## 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.

# ZUGFeRD Guide

> Generate compliant invoices in Germany (ZUGFeRD).

## Introduction

**ZUGFeRD** is a German standard for electronic invoicing designed to bridge the gap between traditional invoices and digital formats. ZUGFeRD combines a standard PDF/A-3 invoice with an embedded XML file containing the structured data. This hybrid approach makes it especially popular in B2B transactions, as it allows both people and accounting software to work with the same document. It is fully aligned with the European Norm `EN 16931`. It is worth noting that ZUGFeRD and [Factur-X](/guides/countries/fr-facturx) are a joint project between Germany and France, and their content is identical.

<Tip>
  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](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 ZUGFeRD 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.

## ZUGFeRD Setup

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

<Steps>
  <Step title="Connect the UN/CEFACT CII app">
    1. Navigate to **Configuration** → **Apps**.
    2. Locate **UN/CEFACT CII** 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="ZUGFeRD invoice workflow" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=de-zugferd" cta="Add to my workspace">
          This workflow will generate an ZUGFeRD XML document and embed it into a PDF.
        </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 Workflow for generating a PDF with a ZUGFeRD XML attachment  theme={"system"}
        {
            "name": "ZUGFeRD invoice",
            "description": "Generate PDF with ZUGFeRD XML attachment",
            "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"
                    },
                    "next": []
                },
                {
                    "id": "58fb4ce0-6626-11f0-b9ab-1bbe1fa4398c",
                    "name": "Sign Envelope",
                    "provider": "silo.close"
                },
                {
                    "id": "3548d720-6623-11f0-b3db-e7255a5da07c",
                    "name": "Generate UN/CEFACT CII Invoice",
                    "provider": "cii.generate",
                    "summary": "ZUGFeRD V2",
                    "config": {
                        "doc_type": "zugferd-v2"
                    },
                    "next": []
                },
                {
                    "id": "56bda1e0-8ef7-11f0-aa0e-dd7c69b95f3c",
                    "name": "Generate PDF",
                    "provider": "pdf",
                    "summary": "English - A4",
                    "config": {
                        "logo_height": 40,
                        "locale": "de",
                        "date_format": "%Y-%m-%d",
                        "layout": "A4",
                        "scripting": false
                    }
                },
                {
                    "id": "c6192a60-abd0-11ef-a013-91c68ca9f44b",
                    "name": "Set State",
                    "provider": "silo.state",
                    "summary": "Set state to `sent`{.state .sent}",
                    "config": {
                        "state": "sent"
                    },
                    "next": []
                }
            ],
            "rescue": [
                {
                    "id": "c94982c0-abd0-11ef-a013-91c68ca9f44b",
                    "name": "Set State",
                    "provider": "silo.state",
                    "summary": "Set state to `error`{.state .error}",
                    "config": {
                        "state": "error"
                    },
                    "next": []
                }
            ]
        }
        ```
      </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 UN/CEFACT CII Invoice**: In "Invoice Output Document Type" select `ZUGFeRD v2`.
        4. **Generate PDF**: 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`.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Running

<Note>
  In your invoice data, make sure to include the [ZUGFeRD 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 include the [ZUGFeRD](https://docs.gobl.org/addons/de-xrechnung-v3) addon. This will add extra validations to ensure the document is compliant with each standard.

## Sample Invoices

<AccordionGroup>
  <Accordion title="ZUGFeRD B2C invoice">
    ```json ZUGFeRD B2C Invoice theme={"system"}
    {
        "$schema": "https://gobl.org/draft-0/bill/invoice",
        "$regime": "DE",
        "$addons": [
            "eu-en16931-v2017",
            "de-zugferd-v2"
        ],
        "$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"
        }
    }
    ```
  </Accordion>

  <Accordion title="ZUGFeRD B2B invoice with additional fields">
    ```json ZUGFeRD B2B Invoice with additional fields theme={"system"}
    {
        "$schema": "https://gobl.org/draft-0/bill/invoice",
        "$regime": "DE",
        "$addons": [
            "eu-en16931-v2017",
            "de-zugferd-v2"
        ],
        "uuid": "019231f1-9128-71fc-b0e2-820af3036d1b",
        "type": "standard",
        "series": "SAMPLE",
        "code": "001",
        "issue_date": "2024-02-13",
        "currency": "EUR",
        "tax": {
            "ext": {
                "untdid-document-type": "380"
            }
        },
        "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",
                        "key": "standard",
                        "rate": "general",
                        "percent": "19%",
                        "ext": {
                            "untdid-tax-category": "S"
                        }
                    }
                ],
                "total": "1800.00"
            }
        ],
        "discounts": [
            {
                "i": 1,
                "reason": "Promotion discount",
                "amount": "10.00",
                "taxes": [
                    {
                        "cat": "VAT",
                        "key": "standard",
                        "rate": "general",
                        "percent": "19%",
                        "ext": {
                            "untdid-tax-category": "S"
                        }
                    }
                ],
                "ext": {
                    "untdid-allowance": "88"
                }
            }
        ],
        "charges": [
            {
                "i": 1,
                "reason": "Freight",
                "amount": "11.00",
                "taxes": [
                    {
                        "cat": "VAT",
                        "key": "standard",
                        "rate": "general",
                        "percent": "19%",
                        "ext": {
                            "untdid-tax-category": "S"
                        }
                    }
                ]
            }
        ],
        "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": "2143.19",
                        "percent": "100%"
                    }
                ],
                "notes": "2 % discount if paid within 2 days\n            Penalty percentage 10% from due date"
            },
            "instructions": {
                "key": "credit-transfer",
                "ref": "0003434323213231",
                "credit_transfer": [
                    {
                        "iban": "NO9386011117947",
                        "bic": "DNBANOKK"
                    }
                ],
                "card": {
                    "last4": "1234",
                    "holder": "John Doe"
                },
                "direct_debit": {
                    "ref": "1234567890",
                    "creditor": "987654321",
                    "account": "DE89370400440532013000"
                },
                "ext": {
                    "untdid-payment-means": "30"
                }
            }
        },
        "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"
        },
        "totals": {
            "sum": "1800.00",
            "discount": "10.00",
            "charge": "11.00",
            "total": "1801.00",
            "taxes": {
                "categories": [
                    {
                        "code": "VAT",
                        "rates": [
                            {
                                "key": "standard",
                                "ext": {
                                    "untdid-tax-category": "S"
                                },
                                "base": "1801.00",
                                "percent": "19%",
                                "amount": "342.19"
                            }
                        ],
                        "amount": "342.19"
                    }
                ],
                "sum": "342.19"
            },
            "tax": "342.19",
            "total_with_tax": "2143.19",
            "payable": "2143.19"
        }
    }
    ```
  </Accordion>
</AccordionGroup>

You can now generate invoices in the two formats 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="How can I view an XML attached to a PDF?">
    For ZUGFeRD 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](https://www.systoolsgroup.com/pdf/extractor/) to extract the XML file.
  </Accordion>
</AccordionGroup>