# Anforderungen an den eInvoice-Validierungsdienst

**Adressat:** Betreiber des Validierungsdienstes `https://api.processweb.de/api/eInvoice`
**Kontext:** Das Fuchs-Intranet erzeugt Rechnungen als ZUGFeRD/Factur-X- bzw. XRechnung-Hybrid
(PDF/A-3 mit eingebetteter CII-XML) und ruft nach der Erzeugung `POST /validatepdf` auf, um
**formale PDF/A-3-Konformität** und **EN 16931-/XRechnung-Regelkonformität** zu prüfen.

**Zielbild:** Der Validator soll **maximalen Funktionsumfang** haben — jede in Deutschland/EU
praktisch vorkommende E-Rechnung (alle gängigen Syntaxen, Profile und Versionen) erkennen,
korrekt klassifizieren und gegen die passenden Regelwerke prüfen.

> **Status 2026-07:** Die ursprüngliche Kernlücke (CII-Dokumente wurden nicht klassifiziert) ist
> behoben — sowohl EN 16931-ZUGFeRD als auch XRechnung 3.0 (CII) werden inzwischen erkannt und
> geprüft (`scenarioMatched=true`, angereichertes Response-Schema). Dieses Dokument bleibt als
> Referenz für den angestrebten **vollen** Funktionsumfang (Abschnitt 4).

---

## 1. Referenz — was Fuchs emittiert

| Profil | Einbettung | GuidelineSpecifiedDocumentContextParameter/ID | Einsatz |
|---|---|---|---|
| ZUGFeRD EN 16931 (COMFORT) | `factur-x.xml` | `urn:cen.eu:en16931:2017` | B2B/B2C, DATEV (Standard) |
| XRechnung 3.0 (CII) | `xrechnung.xml` | `urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0` | B2G (Leitweg-ID vorhanden) |

Beide sind PDF/A-3 (veraPDF-COMPLIANT). Profilwahl automatisch: **Leitweg-ID vorhanden →
XRechnung**, sonst **EN 16931-ZUGFeRD**.

## 2. Kern-Anforderungen (umgesetzt, als Regressionsschutz dokumentiert)

### R1 — XRechnung 3.0 in CII matchen (B2G)
- Match-Kriterium (CII): `rsm:CrossIndustryInvoice/rsm:ExchangedDocumentContext/`
  `ram:GuidelineSpecifiedDocumentContextParameter/ram:ID` =
  `urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0`
- Erwartung: `documentType` gesetzt, `scenarioMatched=true`, EN 16931- **und** XRechnung-Schematron.

### R2 — Reines EN 16931 (CII) matchen (ZUGFeRD/DATEV)
- Match-Kriterium (CII): `…/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID` =
  `urn:cen.eu:en16931:2017` (ohne XRechnung-CIUS-Zusatz).
- Prüftiefe: **nur** das EN 16931-Kern-Schematron (nicht die XRechnung-CIUS-Regeln).

### R3 — Einbettung aus dem Hybrid-PDF robust extrahieren
`/validatepdf` muss die CII-Rechnungs-XML unabhängig vom Dateinamen aus dem `/AF`-Array ziehen
(`factur-x.xml`, `xrechnung.xml`, Altname `zugferd-invoice.xml`). Das Match erfolgt über den
XML-Inhalt/die CustomizationID, nicht über den Dateinamen.

> Historischer Hinweis: Solange die drei CII-Wurzelkinder fälschlich im `ram:`- statt
> `rsm:`-Namespace standen (Fuchs-seitiger Bug, behoben), konnte kein Validator die CustomizationID
> extrahieren. Der Match muss auf `rsm:ExchangedDocumentContext` greifen.

---

## 3. (frei)

## 4. Maximaler Funktionsumfang

### 4.1 Support-Matrix (Syntax × Profil × Version)

| Standard / Profil | Syntax | Versionen | Regelwerk |
|---|---|---|---|
| **EN 16931** (Kern) | CII, UBL | :2017 (+ Amdt.) | EN16931-Schematron (ConnectingEurope) |
| **XRechnung** (CIUS) | CII, UBL | 2.0 – 2.3, **3.0.x**, (4.0) | EN16931 + XRechnung-Schematron (KoSIT) |
| **ZUGFeRD / Factur-X** | CII | 2.0 – **2.4** (Factur-X 1.0/1.07/1.08) | EN16931 (BASIC/COMFORT), EXTENDED |
| ZUGFeRD-Profile | CII | MINIMUM, BASIC WL, BASIC, EN16931, EXTENDED | profilabhängig |
| **Peppol BIS Billing 3.0** | CII, UBL | 3.0.x | EN16931 + Peppol-Schematron |
| Dokumentarten | — | Rechnung (380), Gutschrift (381), Korrektur (384), Storno | UNCL1001 |

> Mindest-Priorität: **XRechnung 2.x** und **ZUGFeRD alle 2.x-Profile**; **Peppol BIS 3.0** und
> **XRechnung 4.0** als Ausbaustufe.

### 4.2 Validierungsschichten (je Dokument, getrennt ausgewiesen)

1. **Syntax / XSD** — CII (D16B/D22B/D25A) bzw. UBL (2.1/2.5).
2. **EN 16931-Schematron** — BR-*, BR-CO-*, BR-DEC-*.
3. **CIUS-Schematron** — XRechnung (BR-DE-*) bzw. Peppol (PEPPOL-*).
4. **Codelisten** — UNCL/EAS/ISO (Währung, Land, Einheit, USt-Kategorie, Zahlungsmittel).
5. **Rechen-/Konsistenzprüfung** — Summen, USt-Aufteilung.
6. **PDF/A** (veraPDF) — Flavour wählbar (`3b` Default; auch `3u`, `2b`, `1b`).
7. **ZUGFeRD/Factur-X-Container** — `/AF`-Verknüpfung, `/AFRelationship`, Subtype `text/xml`,
   XMP-`fx:*`-Metadaten und **Konsistenz** zwischen XMP-ConformanceLevel und Guideline/CustomizationID.

### 4.3 Auto-Erkennung (ohne Vorgabe durch den Aufrufer)

- **Syntax** aus dem Wurzelelement (`rsm:CrossIndustryInvoice` → CII; UBL `Invoice`/`CreditNote`).
- **Profil/Version** aus `GuidelineSpecifiedDocumentContextParameter/ram:ID` (CII) bzw.
  `cbc:CustomizationID` + `cbc:ProfileID` (UBL).
- **Dokumentart** aus `TypeCode` (BT-3).
- Strengstes zutreffendes CIUS automatisch wählen; reines EN 16931 nur Kernregeln.

### 4.4 Erweiterte API-Endpunkte

Bestehend: `verify`, `validate`, `validatepdf`, `validatepdfa`, `doc`, `schema`, `mcp`. Ergänzen:

- **`POST /detect`** — nur Klassifikation (Syntax/Profil/Version/Dokumentart).
- **`POST /validate` mit UBL** — `application/xml` UBL akzeptieren (nicht nur CII).
- **`POST /validatebatch`** — mehrere Dokumente (multipart oder ZIP).
- **Report-Formate** über `Accept`/`?format=`: `json` (Default), `svrl`, `html`.
- **`flavour`-Parameter** auch bei `validatepdf` durchreichen.
- Weiterhin **HTTP 200** bei fachlicher Ablehnung; echte Transportfehler als 400/415/502/504.

### 4.5 Angereichertes Response-Schema

```jsonc
"xml": {
  "syntax": "CII|UBL",
  "standard": "EN16931|XRechnung|ZUGFeRD|Peppol",
  "profile": "EN16931|EXTENDED|XRECHNUNG|BASIC|…",
  "version": "3.0.2",
  "documentType": "XRechnung 3.0 (CII)",
  "customizationId": "urn:…xrechnung_3.0",
  "scenarioMatched": true,
  "documentData": { "invoiceId","issueDate","seller","buyer","leitwegId","totalGross","currency" },
  "layers": [ { "id":"xsd|en16931|cius|codelist|calc", "name","valid","errorCount","warningCount" } ],
  "messages": [ { "level":"error|warning|information","code","rule","message","location","clause","businessTerm" } ]
}
```

- `level` konsequent aus dem SVRL (`fatal`→error, sonst warning).
- `location` als XPath **und**, wo möglich, als Business Term (BT-/BG-Nummer).
- `recommendation` = `accept`, wenn `errorCount=0` (Warnungen erlaubt).

### 4.6 Betrieb / Nicht-funktional

- **Aktuelle Artefakt-Stände**: KoSIT (XRechnung 2.x/3.0.x/4.0), eInvoicing-EN16931, Peppol,
  veraPDF — mit ausgewiesenen Versionen im Report (`engine`, `scenarioVersion`, `rulesetVersion`).
- **Health** (`/verify`) meldet geladene Szenario-/Ruleset-Versionen + Zustand jedes Sub-Validators.
- Robuste Größen-/Timeout-Grenzen dokumentiert; klare 413/504 statt stiller Fehler.

## 5. Abnahmekriterien

1. **ZUGFeRD EN 16931** (`factur-x.xml`, `urn:cen.eu:en16931:2017`): `xml.scenarioMatched=true`,
   `documentType` ≈ `"EN16931 (CII)"`, `pdfa.isCompliant=true`, bei sauberem Beleg `errorCount=0`.
2. **XRechnung 3.0** (`xrechnung.xml`, `…xrechnung_3.0`, mit Leitweg-ID): `scenarioMatched=true`,
   `documentType` ≈ `"XRechnung 3.0 (CII)"`, `pdfa.isCompliant=true`.
3. **Auto-Erkennung** (`POST /detect`): klassifiziert beide korrekt (Syntax/Profil/Version).
4. **UBL-XRechnung** (Fremdbeleg): wird erkannt und geprüft.
5. **PDF/A**: bleibt COMPLIANT (Flavour `3b`).

## 6. Fuchs-seitiges Verhalten

Der Fuchs-Client (`ProcessWebERechnungValidator`) wertet einen reinen **Szenario-Mismatch mit
`errorCount=0` nicht als harten Fehler** (die Rechnung wird nicht zurückgehalten); echte PDF/A-
oder XML-Regelfehler dagegen schon (bei `FailOnError=true` wird der Hybrid zurückgehalten →
Fallback auf Plain-PDF/A).