# ZUGFeRD Validator

> Gehostete REST API und MCP-Client zur automatisierten Validierung von ZUGFeRD, Factur-X und XRechnung E-Rechnungen gegen den europäischen Standard EN 16931.

## Was ist ZUGFeRD Validator?

ZUGFeRD Validator ist ein API-Dienst, der es KI-Agenten und Entwicklern ermöglicht, deutsche und europäische E-Rechnungen automatisch auf Konformität zu prüfen. Die Validierung erfolgt gegen EN 16931 (europäischer Standard für elektronische Rechnungen) mit dem Mustang Project als Validierungsengine.

Unterstützte Formate:
- ZUGFeRD 2.x (alle Profile: MINIMUM, BASIC-WL, BASIC, EN16931, EXTENDED)
- Factur-X (französisches Äquivalent zu ZUGFeRD)
- XRechnung (deutsche Verwaltungsstandard)

## API-Endpunkte

Basis-URL: `https://api.zugferd-validator.de`

### POST /v1/validate
Validiert eine E-Rechnung (PDF oder XML) gegen EN 16931.
- Input: `{ file_content: string (base64), file_type: "pdf"|"xml" }`
- Output: Validierungsergebnis mit Fehlern, Warnungen, Korrekturvorschlägen und Metadaten
- Auth: `X-Api-Key` Header

### POST /v1/extract
Extrahiert das eingebettete XML aus einem ZUGFeRD/Factur-X PDF.
- Input: `{ pdf_content: string (base64) }`
- Output: `{ xml: string }`

### POST /v1/consistency
Prüft ob die sichtbaren PDF-Daten mit den eingebetteten XML-Daten übereinstimmen.
- Input: `{ pdf_content: string (base64) }`
- Output: Konsistenzprüfung mit gefundenen Abweichungen

### GET /v1/keys/me
Gibt Key-Info und heutigen Verbrauch zurück.
- Auth: `X-Api-Key` Header

## MCP-Client

Der MCP-Client (`zugferd-mcp-client`) ermöglicht die Integration in MCP-kompatible KI-Tools.

Installation: `npm install -g zugferd-mcp-client`

Konfiguration:
```json
{
  "mcpServers": {
    "zugferd": {
      "command": "zugferd-mcp-client",
      "env": {
        "ZUGFERD_API_KEY": "zv_..."
      }
    }
  }
}
```

Verfügbare MCP-Tools:
- `validate_invoice` — Rechnung validieren
- `extract_xml` — XML aus PDF extrahieren
- `check_consistency` — Konsistenz prüfen

## Preise

- **Free**: 20 Anfragen/Tag, kostenlos, kein Kreditkarte
- **Pro**: 500 Anfragen/Tag, €49/Monat
- **Ultra**: Unbegrenzte Anfragen/Tag (Fair Use Policy), €149/Monat

## Authentifizierung

Alle API-Anfragen erfordern einen API-Key im `X-Api-Key` Header.

**Demo-Key (sofort nutzbar, kein Account nötig):** `zv_demo_public_zugferd_2026`
- Limit: 3 Anfragen pro Tag und IP-Adresse
- Kein Sign-up, keine Kreditkarte

Eigenen kostenlosen API-Key (20 Anfragen/Tag) holen: https://zugferd-validator.de/portal.html

## Validierungsergebnis (Beispiel)

```json
{
  "valid": false,
  "format": "ZUGFeRD 2.4.0",
  "profile": "EN16931",
  "summary": "2 Fehler, 1 Warnung gefunden",
  "errors": [
    {
      "severity": "error",
      "rule_id": "BR-DE-1",
      "field": "BT-34",
      "message": "Die USt-ID des Verkäufers muss angegeben werden.",
      "fix_suggestion": "Füge ram:SpecifiedTaxRegistration mit schemeID='VA' hinzu.",
      "xpath": "//rsm:CrossIndustryInvoice/..."
    }
  ],
  "metadata": {
    "invoice_number": "RE-2026-001",
    "seller": "Musterfirma GmbH",
    "total_amount": "1190.00",
    "currency": "EUR"
  }
}
```

## Links

- Landing Page: https://zugferd-validator.de
- API-Dokumentation: https://docs.zugferd-validator.de
- API-Key Portal: https://zugferd-validator.de/portal.html
- Anbieter: OPM GmbH, Stuttgart