ZUGFeRD API: eingebettete XML aus PDFs per REST prüfen
ZUGFeRD 2.x und Factur-X sind hybride PDFs mit eingebetteter Rechnungs-XML. Statt jede Datei im Browser zu öffnen, prüfen Sie sie per REST: POST an /api/v1/validate, JSON zurück mit valid, Format und jeder verletzten Regel-ID. Ausgewertet wird die erste eingebettete Datei; PDF/A-3 und XMP-Metadaten werden nicht geprüft. Kostenlos 50 Prüfungen pro Monat und Schlüssel, Schlüssel sofort ohne Zahlung. Beta, ohne Verfügbarkeitszusage — kein offizieller Dienst der KoSIT und keine Zertifizierung.
Hybride PDFs in Software und Pipelines prüfen
Ein ZUGFeRD- oder Factur-X-Dokument ist ein lesbares PDF, in dem die Rechnungs-XML steckt. Die API nimmt dieses PDF so entgegen, wie es Ihr ERP, Ihr Archiv oder Ihre CI liefert — ohne dass Sie die XML vorher selbst herausziehen müssen. Typische Einsätze: Eingangsrechnungen vor dem Verbuchen prüfen, Batch-Läufe über ältere Bestände, oder ein Check vor dem Versand an Geschäftspartner. Ihre Software sendet die Datei per HTTP und erhält strukturierte Fehler mit Regelnummer.
Mehr dazu: API-Dokumentation und Schlüssel
Erste eingebettete Datei — was die API nicht prüft
Geprüft werden die veröffentlichten Schematron-Regeln der KoSIT (EN 16931 und, bei XRechnung-Kennung im Profil, XRechnung 3.0.2) für die ausgelesene CII- oder UBL-XML. Eine XSD-Schemaprüfung findet nicht statt; das Ergebnis ist daher nicht identisch mit dem vollständigen KoSIT-Prüftool. Bei PDFs wird nur die erste eingebettete Datei als XML gelesen — nicht PDF/A-3, nicht XMP-Metadaten und nicht der Einbettungsname (factur-x.xml oder zugferd-invoice.xml). Liegt vor der Rechnungs-XML ein anderer Anhang, laden Sie die extrahierte XML direkt hoch. ZUGFeRD 1.x (älteres CII-Wurzelelement CrossIndustryDocument) wird nicht unterstützt — nur ZUGFeRD 2.x und Factur-X. Profile Minimum und Basic WL scheitern an EN-16931-Regeln; das ist korrekt, denn sie gelten nicht als E-Rechnung. Formal „keine Fehler“ heißt nicht steuerlich ordnungsgemäß. Rechnungsdateien werden nur im Arbeitsspeicher verarbeitet, nicht gespeichert und nicht an KI-Dienste übermittelt.
Mehr dazu: Grenzen der API · Was der Browser-Validator bei ZUGFeRD prüft
Wann Browser-Validator, API oder Reparatur
Unter Prüfen läuft dieselbe Schematron-Prüfung für einzelne ZUGFeRD-PDFs im Browser — ohne API-Schlüssel und ohne KI. Die automatische Reparatur unter /service kann behebbare Formatfehler in der XML korrigieren und nutzt dafür optional KI; die Validate-API repariert nichts und sendet nichts an KI. Für Entwickler, die viele hybride PDFs oder Pipelines anbinden, ist die API der passende Einstieg.
Mehr dazu: ZUGFeRD im Browser prüfen · ZUGFeRD prüfen: Überblick · Automatisch reparieren
Limits: Free jetzt, bezahlt später
Free ist jetzt verfügbar: 50 Prüfungen pro Monat und Schlüssel, höchstens 60 Anfragen pro Minute. Bezahlte Tarife sind geplant und noch nicht buchbar; den aktuellen Stand zu Limits und Preisen finden Sie nur auf der API-Dokumentationsseite. Das Angebot ist Beta ohne Verfügbarkeitszusage; bei Missbrauch können Schlüssel gesperrt werden.
Mehr dazu: Limits und Tarife
Drei Schritte zum ersten API-Aufruf
1. Schlüssel per E-Mail auf der Dokumentationsseite holen. 2. ZUGFeRD-/Factur-X-PDF als Multipart-Feld file an POST /api/v1/validate senden (max. 2,5 MB) — oder die Rechnungs-XML als Body mit Content-Type application/xml bzw. ebenfalls als Multipart. 3. curl-, Node-Beispiele und die OpenAPI-3.1-Spezifikation stehen dort.
Mehr dazu: Schnellstart mit curl · OpenAPI JSON · OpenAPI YAML
Ohne lokales PDF-Extrahieren und ohne KoSIT-Jar
Bei hybriden PDFs entfällt das eigene Extrahieren der eingebetteten XML; Sie müssen auch kein Java-Prüftool betreiben oder Regelpakete aktualisieren. Dafür entfällt die XSD-Schemaprüfung des KoSIT-Jars, und das Ergebnis ist nicht identisch mit dem vollständigen KoSIT-Prüftool. Die Prüfung ersetzt keine Steuerberatung.
Mehr dazu: Zur API-Dokumentation
Häufige Fragen
Was kostet die ZUGFeRD-API?
Der Free-Tarif ist kostenlos: 50 Prüfungen pro Monat und Schlüssel, ohne Zahlungsmittel. Bezahlte Tarife sind geplant und noch nicht buchbar; den aktuellen Stand sehen Sie auf der API-Dokumentationsseite.
Ist das ein offizieller oder zertifizierter KoSIT-Dienst?
Nein. Es ist ein eigenes Angebot und führt die veröffentlichten KoSIT-Schematron-Regeln aus. Das ist keine Zertifizierung und kein behördlicher Dienst.
Prüft die API PDF/A-3, XMP und den Einbettungsnamen?
Nein. Bei PDFs wird nur die erste eingebettete Datei als XML geprüft. PDF/A-3, XMP-Metadaten und der Dateiname der Einbettung (factur-x.xml oder zugferd-invoice.xml) werden nicht validiert.
Prüft die API auch gegen XSD-Schemas?
Nein. Es laufen nur die veröffentlichten Schematron-Regeln (EN 16931 und bei XRechnung-Kennung XRechnung 3.0.2). Ohne den XSD-Schritt des KoSIT-Jars ist das Ergebnis nicht identisch mit dem vollständigen KoSIT-Prüftool.
Werden meine Rechnungen gespeichert?
Nein. An die Validate-API gesendete Rechnungsdateien werden nur im Arbeitsspeicher verarbeitet, nicht gespeichert und nicht an KI-Dienste übermittelt. Einzelheiten stehen in der Datenschutzerklärung.
Wird Factur-X genauso geprüft?
Ja — derselbe API-Pfad (erste eingebettete XML, keine PDF/A-3-/XMP-Prüfung). Den Factur-X-eigenen Überblick zu Naming, Profilen und Frankreich finden Sie unter /factur-x-api.