---
status: Active
lastUpdated: 2026-07-18
applyTo:
  - "Fuchs/Services/ERechnungMapper.cs"
  - "Fuchs/Services/ERechnungService.cs"
  - "Fuchs/Services/ERechnungSettings.cs"
  - "Fuchs/Services/InvoiceRecipientAddress.cs"
  - "Fuchs/Services/InvoiceService.cs"
  - "Fuchs/code/FuchsPdf.cs"
  - "eRechnungLib/**"
relatedDecisions:
  - "0005-pdf-generation-and-erechnung.md"
  - "0012-erechnung-single-pdfa-engine-pipeline.md"
---

# eRechnung output (ZUGFeRD/Factur-X)

## Summary
Finalized invoices are emitted as a **ZUGFeRD 2.4 / Factur-X** hybrid: the FuchsPdf visual PDF
with the EN 16931 **CII XML** embedded, in a formally conformant **PDF/A-3**. This makes invoices
DATEV-ingestible and satisfies the B2B/B2G e-invoicing mandate. The library doing the structured
XML + PDF/A-3 work is the `eRechnungLib` submodule; Fuchs supplies the invoice data and the visual
PDF.

## How it works

```
Editor (structured recipient dialog)
   → InvoiceDraftEditService  (address delta = JSON object, stored in CustomValues.sendToAddress)
   → fds__setInvoice/…        (persisted; dedicated SendToAddressJson column + composed SendToAddress)
   → InvoiceService.RenderInvoicePdfBytesAsync(final)
        ├─ FuchsPdf.DocToPdfBytesRaw(doc)          → visual PDF (no Spire PDF/A)
        └─ IERechnungService.TryBuildHybridPdf
               ├─ ERechnungMapper.BuildEInvoice     FdsInvoiceData → eRechnungLib.Model.Invoice
               └─ EInvoice.ToZugferd(EN16931, raw)  → PDF/A-3 + Factur-X hybrid (bundled sRGB ICC)
```

- **Single PDF/A engine (ADR 0012).** eRechnungLib owns the one PDF/A-3 layer. For the eRechnung
  path the Spire PDF/A step is skipped (`DocToPdfBytesRaw`); Spire stays only for on-screen preview
  rasterisation. This avoids a conflicting second output intent / `pdfaid` marker.
- **Structured recipient address.** `InvoiceRecipientAddress` holds the EN 16931 buyer fields
  (name, street, post code, city, country BT-55, optional VAT id BT-48). It is edited via a
  dialog form (`$inv.eAddress` in `fis.inv_shared.js`), prefilled from `fds__prepInvoice`'s
  `invoiceaddressData`, and carried as a JSON object through the draft cache. A private person
  (no VAT id) is fully valid — B2C stays effortless. The free-text `SendToAddress` is composed
  from it so the PDF layout is unchanged.
- **Mapping.** `ERechnungMapper` maps the Fuchs invoice to the EN 16931 model: seller = Fuchs
  (constants mirroring the FuchsPdf letterhead — name, Steuernummer BT-32, IBAN/BIC), buyer =
  the structured recipient, lines from the invoice items, §13b → reverse charge (category AE +
  exemption reason). VAT breakdown and totals are recomputed by the library.
- **Feature flag & fallback.** Emission is gated by `Fuchs:ERechnung:Enabled` (off until fully
  validated). `IERechnungService` returns `null` on disable **or any failure**, so
  `RenderInvoicePdfBytesAsync` falls back to the plain Spire PDF/A — invoicing never breaks.
- **Formal verification.** `Fuchs:ERechnung:Validation:ServiceUrl` is the seam for an external
  online veraPDF (PDF/A-3) + ZUGFeRD validator; until the URL is provisioned, verification is
  reported as not-configured.

## Key files
- `Fuchs/Services/InvoiceRecipientAddress.cs` — structured buyer address, composition, conformity.
- `Fuchs/Services/ERechnungMapper.cs` — `FdsInvoiceData` → `eRechnungLib.Model.Invoice`.
- `Fuchs/Services/ERechnungService.cs` / `ERechnungSettings.cs` — hybrid production + config.
- `Fuchs/Services/InvoiceService.cs` — wiring in `RenderInvoicePdfBytesAsync`.
- `Fuchs/code/FuchsPdf.cs` — `DocToPdfBytesRaw` (render-only visual PDF).
- `Fuchs/js/intranet/modules/fis.inv_shared.js` — `$inv.eAddress` structured dialog.
- `Fuchs_Database` — `fds__invoices.SendToAddressJson`, `fds__getCompanyAddressJson`,
  `fds__prepInvoice.invoiceaddressData`, `fds__createInvoice`/`setInvoice`/`getInvoice`.
- `eRechnungLib/**` — CII/UBL serialization, EN 16931 validation, `FacturXPdfBuilder` (PDF/A-3).

## Related decisions
- [`0005-pdf-generation-and-erechnung.md`](../Decisions/0005-pdf-generation-and-erechnung.md)
- [`0012-erechnung-single-pdfa-engine-pipeline.md`](../Decisions/0012-erechnung-single-pdfa-engine-pipeline.md)