> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/e-invoicing-integrations/zugferd.md).

# ZUGFeRD

## Overview

The ZUGFeRD integration embeds structured invoice XML (CII format, ZUGFeRD 2.3) inside PDF documents using the extended profile by default. Younium builds an `InvoiceDescriptor` from invoice and legal entity data, validates basic or extended models, serialises XML, and attaches it to the PDF as `ZUGFeRD-invoice.xml` with MIME type `text/xml` and AF relationship `Alternative`.

## Authentication

There is no external connection and nothing to authenticate. The ZUGFeRD XML is embedded inside Younium when an invoice PDF is generated for a legal entity that has ZUGFeRD enabled.

## Profiles supported

| Profile                                                                 | Validator     | Notes                                                      |
| ----------------------------------------------------------------------- | ------------- | ---------------------------------------------------------- |
| **Basic**, **Comfort**                                                  | Supported     | Documents are built to the **Extended** profile by default |
| **Extended**                                                            | Supported     | The default profile                                        |
| **Minimum**, **BasicWL**, **XRechnung**, **XRechnung1**, **EReporting** | Not available | Selecting one of these does not produce a document         |

Saved XML uses `ZUGFeRDVersion.Version23`, format `CII`, embedded filename `ZUGFeRD-invoice.xml`.

## Eligibility and line filtering

Invoice lines are filtered with `FilterInvoiceLinesForDocument` using invoice type and `InvoiceSettings` before modelling (same pattern as other document outputs). Validation exceptions surface as `ZugferdValidationException`.

## General information mapping

| Younium Field                 | ZUGFeRD descriptor                                             |
| ----------------------------- | -------------------------------------------------------------- |
| `Invoice.InvoiceNumber`       | Invoice number                                                 |
| `Invoice.InvoiceDate`         | Invoice date                                                   |
| `Invoice.Currency.Code`       | Currency (must match supported enum mapping)                   |
| `Invoice.Notes`               | Note on descriptor                                             |
| Credit or negative total      | `InvoiceType.CreditNote`                                       |
| `Invoice.Status == Cancelled` | `InvoiceType.Correction`                                       |
| Fixed                         | Business process `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0` |

## Party mapping — seller

| Younium Field                                   | ZUGFeRD party               |
| ----------------------------------------------- | --------------------------- |
| `ApplicationLegalEntity` name, address, tax IDs | Seller party block          |
| `ApplicationLegalEntity.IBAN`, `BIC`            | Payment means on descriptor |

## Party mapping — buyer

The buyer address (street, postcode, city) is taken from the invoice's own address — the same address printed on the invoice PDF. If the invoice has no address of its own, Younium falls back to the account's default invoice address. The buyer country is read only from the invoice address and does not use this fallback.

| Younium Field                                                                     | ZUGFeRD party                                           |
| --------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `Invoice.InvoiceAddress`, falling back to `Invoice.Account.DefaultInvoiceAddress` | Buyer street, postcode, city                            |
| `Invoice.InvoiceAddress` country                                                  | Buyer country code                                      |
| `Invoice.Account.Name`                                                            | Buyer name                                              |
| Domestic vs cross-border                                                          | Affects tax category on lines (`isDomesticTransaction`) |

> **Note on buyer address vs. buyer country:** The buyer address falls back to the account's default invoice address when the invoice has none, but the buyer country never does — it always comes from the invoice address, since it also decides the domestic/foreign VAT category on the invoice.

Optional buyer IBAN from `ZugferdSettings` buyer IBAN fallback configuration.

## Line item mapping

| Younium Field                                   | ZUGFeRD line                                            |
| ----------------------------------------------- | ------------------------------------------------------- |
| Line net amounts, quantity, product/charge text | Trade line items                                        |
| `TaxItems`                                      | Tax category per line (see VAT exemption reasons below) |
| Extended profile                                | Additional extended line fields                         |

Tax breakdown groups by category and VAT rate; discrepancies between line tax sum and invoice tax are logged as warnings.

### VAT exemption reasons

The same reason text and code are used for a tax category wherever it appears — on the invoice-level VAT breakdown and on every line carrying that category — so the two always agree.

| Tax category               | Reason text            | VATEX code  |
| -------------------------- | ---------------------- | ----------- |
| E — Exempt from VAT        | Exempt from VAT        | —           |
| G — Export outside the EU  | Export outside the EU  | VATEX-EU-G  |
| AE — Reverse charge        | Reverse charge         | VATEX-EU-AE |
| K — Intra-Community supply | Intra-Community supply | VATEX-EU-IC |
| S — Standard rate          | None                   | None        |
| Z — Zero rate              | None                   | None        |

> **Note on standard and zero-rated invoices:** EN 16931 forbids a VAT exemption reason on a standard-rated or zero-rated invoice line or breakdown. Younium omits the reason entirely for categories S and Z, so a domestic invoice at the standard or zero rate validates correctly against the KoSIT validator and equivalents.

## Payment and totals mapping

| Younium Field       | ZUGFeRD totals     |
| ------------------- | ------------------ |
| Sum of line nets    | `lineTotalAmount`  |
| `Invoice` tax total | `taxTotalAmount`   |
| Grand total         | `grandTotalAmount` |
| Amount due          | `duePayableAmount` |

Rounded to two decimals with away-from-zero rounding.

## Credit notes and corrections

| Condition                      | Descriptor type | References                                                                                                 |
| ------------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------- |
| Credit invoice                 | `CreditNote`    | Prior invoice references via `ZugferdReferenceHelper`                                                      |
| Cancelled invoice              | `Correction`    | Cancellation receipt + references                                                                          |
| Custom field “correction” flag | `Correction`    | `ZugferdSettings.IsCorrectionInvoiceCustomFieldMappingField` — truthy values `true`, `1`, `yes`, `y`, `on` |

Tenant-specific custom mappings are applied after the settings fallbacks above.

## Custom fields

Correction flag uses a configured field configuration ID; renaming the underlying custom field without updating settings breaks correction detection.

Allowed custom mapping targets are constrained by `ZugferdAllowedFieldsProvider` (integration maintenance).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.younium.com/e-invoicing-integrations/zugferd.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.