RechnungsAPI Playground: Vollständiger Leitfaden für alle API-Use-Cases
Dieser Guide erklärt alle zentralen Playground-APIs im Detail: Wann Sie welche API nutzen, welche Eingaben erforderlich sind, welche Ergebnisse Sie erhalten und wie Sie typische Fehler vermeiden.
Der RechnungsAPI Playground ist so aufgebaut, dass Fachbereiche und Entwickler ohne lange Einarbeitung produktiv werden. Sie können Rechnungsdaten extrahieren, XRechnung und ZUGFeRD erzeugen, Dokumente validieren und sogar E-Mail-basierte Workarounds für Legacy-Prozesse umsetzen.
Produktvideo (Überblick)
Video wird über YouTube bereitgestellt.
Welche Funktionen bietet der Playground insgesamt?
- PDF-Rechnung analysieren und strukturierte Daten als JSON extrahieren
- XRechnung (XML) direkt aus JSON erzeugen
- ZUGFeRD aus JSON und optional mit PDF-Kombination erzeugen
- ZUGFeRD-PDFs über Template-Engine mit eigenem Corporate Design erstellen
- XRechnung- und ZUGFeRD-Dokumente gegen EN 16931 validieren
- E-Mail-Workflow als Workaround nutzen, wenn direkte Integration fehlt
Playground APIs im Detail
PDF Analyse
Extrahiert strukturierte Rechnungsdaten aus einer PDF-Rechnung. Ideal als Startpunkt für bestehende PDF-Only Prozesse.
Problem für Fachbereiche
Fachbereiche erhalten Rechnungen oft nur als PDF. Um die Daten in ERP, Buchhaltung oder E-Rechnungsprozesse zu überführen, müssten sie manuell abgetippt werden – fehleranfällig und zeitaufwändig.
So löst die API
Die API analysiert die PDF automatisch und extrahiert strukturierte Daten (Auftraggeber, Empfänger, Beträge, Positionen) als JSON. Fachbereiche erhalten maschinenlesbare Daten ohne manuelle Erfassung; das Ergebnis kann direkt in Folge-APIs weiterverarbeitet werden.
/api/v1/zugferd/createJSONFromAnalysedPdf
Input
- - pdfInvoiceBase64 (Base64-codiertes PDF)
Output
- - invoice-Objekt mit Feldern für Kopf-, Parteien-, Steuer- und Positionsdaten
- - Hinweise auf fehlende oder unsichere Werte (abhängig vom Dokument)
How to use
- 1. PDF im Playground hochladen
- 2. API ausführen und extrahiertes JSON prüfen
- 3. Pflichtfelder ergänzen und für Folge-APIs nutzen
Best practices
- Bei gescannten PDFs ggf. OCR-Qualität prüfen
- Extrahierte Beträge immer gegen Originalbeleg plausibilisieren
XRechnung aus JSON
Erzeugt eine valide XRechnung (XML) direkt aus strukturierten JSON-Daten.
Problem für Fachbereiche
Öffentliche Auftraggeber und viele B2B-Partner verlangen XRechnung. Die manuelle Erstellung von valideem XML erfordert tiefes Wissen zu EN 16931 und XRechnung-Schemas – für Fachbereiche kaum umsetzbar.
So löst die API
Die API wandelt vertraute JSON-Daten in valides XRechnung-XML um. Fachbereiche liefern strukturierte Rechnungsdaten; die API übernimmt Schema-Konformität, Pflichtfelder und Summenlogik.
/api/v1/zugferd/createXinvoiceFromJson
Input
- - invoice (JSON nach EN 16931 Mapping)
Output
- - xinvoiceXML (strukturierte XML-Ausgabe)
- - xInvoiceErrorList bei fachlichen/formatbezogenen Problemen
How to use
- 1. JSON im Playground einfügen oder aus PDF-Analyse übernehmen
- 2. API ausführen und XML-Ergebnis prüfen
- 3. Bei Fehlern die Feld- und Regelhinweise in der UI abarbeiten
Best practices
- Seller/Buyer Pflichtfelder vollständig pflegen
- Summenlogik (Line totals, VAT breakdown, doc totals) konsistent halten
ZUGFeRD aus JSON + PDF
Kombiniert strukturierte Rechnungsdaten mit einem PDF und erzeugt ein ZUGFeRD-konformes Ergebnis.
Problem für Fachbereiche
Fachbereiche wollen ihr gewohntes Rechnungs-PDF-Layout behalten, müssen aber strukturierte E-Rechnungsdaten (XML) anhängen. PDF und XML korrekt zu verknüpfen ist technisch anspruchsvoll.
So löst die API
Die API verbindet das bestehende PDF mit strukturierten JSON-Daten und erzeugt ein valides ZUGFeRD PDF/A-3. Das Layout bleibt erhalten; die eingebetteten Daten erfüllen die E-Rechnungsnorm – ohne eigene Entwicklung.
/api/v1/zugferd/createZugferdFromJson
Input
- - invoice (JSON)
- - invoicePdf64 (Base64-PDF)
Output
- - zugferd (Base64-PDF/A-3)
- - zugferdErrorList und xInvoiceErrorList bei Regelverstößen
How to use
- 1. PDF hochladen und JSON bereitstellen
- 2. API starten und ZUGFeRD-PDF herunterladen
- 3. Warnungen/Fehler pro BR-Regel im Playground auswerten
Best practices
- Fehlerlisten immer bis auf Regel-ID-Ebene beheben (z. B. BR-S-08)
- Insbesondere VAT- und Summenfelder strikt konsistent berechnen
Template-basierte ZUGFeRD-PDF-Erzeugung
Erzeugt ZUGFeRD-konforme PDFs auf Basis Ihrer eigenen Templates – markenkonform und rechtlich verpflichtend in Deutschland ab 2027.
Problem für Fachbereiche
Fachbereiche brauchen markenkonforme Rechnungs-PDFs und müssen ab 2027 ZUGFeRD liefern. Viele haben weder Design-Tools noch technische Ressourcen, um beides zu vereinen.
So löst die API
Die API erzeugt ZUGFeRD-PDFs aus JSON über Ihre eigenen Templates. Sie pflegen das Corporate Design einmal; die API liefert konforme, rechtsgültige E-Rechnungen – ohne Grafik- oder Programmierkenntnisse.
/api/v1/zugferd/createInvoicePdfFromJson
Input
- - invoice (JSON)
- - templateId
Output
- - ZUGFeRD-PDF (Base64), fileName, fileExtension
- - optional Zugferd-/XInvoice-Fehlerlisten
How to use
- 1. Template-ID im Playground setzen
- 2. JSON-Daten einfügen
- 3. ZUGFeRD-PDF generieren
Best practices
- Template-Versionen sauber versionieren
- ZUGFeRD ist ab 2027 in Deutschland Pflicht – frühzeitig testen.
XRechnung Validierung
Validiert XRechnungs-XML gegen EN 16931/XRechnung-Regeln und liefert strukturierte Fehlerrückmeldungen.
Problem für Fachbereiche
XRechnung-Dokumente werden erst beim Empfänger abgelehnt, wenn Schema- oder Business-Regeln verletzt sind. Ablehnungen bedeuten Nacharbeit, Verzögerungen und schlechtere Lieferantenbewertungen.
So löst die API
Die API prüft XML vor dem Versand. Fachbereiche erhalten eine klare Fehlerliste mit Position und Regel-ID und können Verstöße beheben, bevor die Rechnung verschickt wird – keine bösen Überraschungen beim Empfänger.
/api/v1/zugferd/validateXinvoiceXml
Input
- - xinvoiceXML (String/XML)
Output
- - isValid + messages
- - xInvoiceErrors mit id, location, schemaFile
How to use
- 1. XML einfügen oder hochladen
- 2. Validierung ausführen
- 3. Regelverstöße in den Quellfeldern korrigieren
Best practices
- Schema- und Business-Regeln getrennt betrachten
- Bei wiederkehrenden Fehlern Mapping-Logik zentral anpassen
ZUGFeRD PDF Validierung
Prüft bestehende ZUGFeRD-PDFs inkl. eingebettetem XML auf Konformität und zeigt BR-Fehler mit Kontext an.
Problem für Fachbereiche
Fachbereiche erstellen ZUGFeRD-PDFs, wissen aber nicht, ob sie gültig sind. Ungültige Dokumente werden vom Empfänger abgelehnt – mit Verzögerungen und manueller Nacharbeit.
So löst die API
Die API prüft sowohl PDF als auch eingebettetes XML gegen EN 16931. Es gibt eine klare Ja/Nein-Antwort sowie eine detaillierte Fehlerliste, damit Fachbereiche Probleme vor dem Versand beheben können.
/api/v1/zugferd/validateZugferdPdf
Input
- - zugferdFile64 (Base64-PDF)
Output
- - valid, numberOfZugferdErrors, zugferdErrors[] mit id/type/location/schema
How to use
- 1. ZUGFeRD-PDF hochladen
- 2. Validator starten
- 3. Fehlerliste blockweise anhand BR-IDs korrigieren
Best practices
- Die API-Meldung 'File was validated' bedeutet nur: Prüfung wurde ausgeführt
- Ausschlaggebend ist das Feld valid + die strukturierte Fehlerliste
Fazit
Mit dem RechnungsAPI Playground können Sie Ihren gesamten E-Rechnungsprozess abbilden: von PDF-Eingang über JSON-Mapping bis zu validen XRechnung- und ZUGFeRD-Ausgaben. Für Unternehmen mit Legacy-Umgebungen bietet der E-Mail-Workflow zusätzlich einen praktischen Workaround, bis die direkte API-Integration vollständig umgesetzt ist.