E-Rechnung per API & MCP erstellen: ZUGFeRD / Factur-X mit fakturai (JSON, Python, Agenten)

Praktische Schritte: E-Rechnung per API & MCP mit fakturai erzeugen

1. Bestehende Rechnungen zuerst prüfen (Validator-CTA) — Laden Sie Ausgangs- oder Eingangs-PDFs in den kostenlosen Validator. So stellen Sie sicher, dass Stammdaten, Positionen und Prozesse bereits kompatibel sind, bevor Sie API-Aufrufe bauen.
2. Authentifizierung einrichten — Nach Registrierung erhalten Sie einen API-Key. Übergeben Sie ihn als X-API-Key Header (oder Bearer Token, je nach Dokumentation). Für KI-Agenten und Tools: nutzen Sie den MCP-Server (stdio via uvx oder Remote).
3. Payload vorbereiten (allgemeines Rechnungsmodell) — Sammeln Sie Pflichtfelder: invoice_number, invoice_date, due_date, seller (Name, Adresse, USt-ID), buyer, lines (description, quantity, unit_price netto, vat_rate). Optionale Felder für Notes, Payment, Profile.

   {
     "invoice_number": "RE-2026-042",
     "invoice_date": "2026-06-11",
     "due_date": "2026-06-25",
     "seller": {
       "name": "Muster GmbH",
       "street": "Musterstr. 1",
       "zip": "12345",
       "city": "Berlin",
       "country": "DE",
       "vat_id": "DE123456789"
     },
     "buyer": {
       "name": "Kunde AG",
       "street": "Kundenweg 2",
       "zip": "54321",
       "city": "München",
       "country": "DE",
       "vat_id": "DE987654321"
     },
     "lines": [
       { "description": "Beratung und Implementierung", "quantity": 5, "unit_price": "1200.00", "vat_rate": 19 },
       { "description": "Reisekostenpauschale", "quantity": 1, "unit_price": "250.00", "vat_rate": 19 }
     ],
     "notes": "Zahlbar innerhalb 14 Tagen netto."
   }

4. API-Aufruf (HTTP)

   curl -X POST https://fakturai.de/api/v1/invoices \
     -H "X-API-Key: YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d @payload.json \
     -o rechnung-RE-2026-042.zugferd.pdf

   Die Antwort ist die KoSIT-geprüfte ZUGFeRD/Factur-X PDF/A-3b (mit eingebettetem CII-XML). Optional: reines XML oder XRechnung-Variante über Parameter/Profile.
5. MCP für Agenten (Claude, Cursor, n8n, eigene Tools) — Mit dem MCP-Server (uvx --from erechnung erechnung-mcp oder Remote-Endpunkt) stehen Tools wie generate_einvoice und validate_einvoice zur Verfügung. Agenten können direkt strukturierte Rechnungen erzeugen und validieren lassen – ohne eigenen HTTP-Code.

   Beispiel-Prompt für Agenten: „Erzeuge eine ZUGFeRD COMFORT E-Rechnung für die oben genannten Daten über fakturai MCP und liefere die Datei + KoSIT-Report.“

6. Datei empfangen, prüfen und GoBD-konform archivieren — Nur bei „ACCEPT“ durch den KoSIT-Validator wird die Datei ausgeliefert. Speichern Sie PDF/A-3b + XML originalgetreu (unversehrt) + Verfahrensdokumentation (Ihre Verantwortung).

Was fakturai prüft (das KoSIT-Accept-Gate)

fakturai erzeugt ZUGFeRD/Factur-X-Rechnungen und validiert sie vor der Auslieferung in mehreren Schritten:

• PDF/A-3b + XSD-Schema-Prüfung (strukturell korrekt)
• Mustang + veraPDF (Schematron-Business-Rules inkl. deutscher Profile BR-DE/PEPPOL)
• Offizieller KoSIT-Validator der deutschen Finanzverwaltung → Ergebnis „ACCEPT“

Nur wenn alle Prüfungen bestanden sind, erhalten Sie die Datei. Das ist unser zentrales Qualitäts- und Vertrauensmerkmal: die Rechnung ist formatseitig nachweislich durch die Referenz-Engine der Behörde akzeptiert. Hard-Failures blocken; bestimmte Hinweise sind advisory.

Was fakturai nicht ersetzt (und nicht verspricht)

fakturai prüft und erzeugt Format (EN 16931 / ZUGFeRD / Factur-X / XRechnung) und liefert eine KoSIT-acceptierte Datei.

• Die inhaltliche Richtigkeit, steuerliche Einordnung, Umsatzsteuerkorrektheit, GoBD-Archivierungspflichten und Verfahrensdokumentation bleiben allein beim Rechnungsaussteller (siehe GHOA-1671).
• fakturai ersetzt keine Buchhaltungssoftware, keine Steuerberatung, keine Rechnungsprüfung/Approval und keine Lexoffice-/sevdesk-ähnliche Gesamtlösung.
• Keine Garantien auf Annahme durch Empfänger, keine Rechtsberatung, keine Haftungsübernahme für inhaltliche Fehler.

Checkliste: API/MCP-Integration

• [ ] Bestehende Rechnungen im Validator geprüft
• [ ] API-Key / MCP-Verbindung eingerichtet
• [ ] Payload mit korrekten USt-IDs, Netto-Preisen, MwSt-Sätzen und Pflichtangaben
• [ ] Aufruf testet zuerst im Test-Modus (falls verfügbar)
• [ ] Empfangene Datei auf KoSIT-ACCEPT + PDF/A-3b geprüft
• [ ] Archivierung (original + XML + eigene Verfahrensdoku) eingerichtet
• [ ] In n8n/Make/Zapier/Backend/Agent eingebaut und End-to-End getestet

Nächster Schritt

1. Kostenlos validieren — laden Sie eine Probe-Rechnung hoch: /de/validator
2. API-Key anfordern — für produktive Nutzung und höhere Limits
3. Dokumentation lesen — volles Schema, Endpoints, Beispiele: /de/docs/api
4. MCP direkt in Agenten nutzen — siehe /de/blog/e-rechnung-api-agenten und Registry-Einträge