Validieren, verstehen, beheben

Ironfang Finance prüft strukturierte E-Rechnungen, ob XRechnung, ZUGFeRD / Factur-X oder Peppol, gegen genau die veröffentlichten Regeln ihres Formats und meldet jeden Befund mit seiner ursprünglichen Regelkennung. Probieren Sie es ohne Konto im Browser aus, oder führen Sie dieselben Prüfungen aus Ihrem eigenen Code aus.

Neu bei E-Rechnungsformaten und ihren Regeln? Im Wissensbereich E-Rechnung finden Sie die Grundlagen, geführte Lernpfade und die kostenlosen Validatoren.

Format wählen

Jedes Format wird auf dieselbe Weise geprüft: Das Dokument durchläuft seine Prüfschritte der Reihe nach, jedes Ergebnis nennt das Regelwerk, gegen das geprüft wurde, und eine Dienststörung wird nie als ungültige Rechnung gemeldet. Was Sie einreichen und was die Prüfungen abdecken, hängt vom Format ab.

Die API validiert Peppol über V1 oder V2, XRechnung und ZUGFeRD / Factur-X über V2; der Leitfaden zu V1 und V2 erklärt, welche Version was abdeckt und wie sich ihre Ergebnisse unterscheiden.

Im Browser ausprobieren

Jeder kostenlose Validator funktioniert im Browser ohne Konto. Anonyme Dokumente und Ergebnisse werden nicht aufbewahrt.

1. Öffnen Sie den Validator für Ihr Format und probieren Sie sein Beispiel aus, oder laden Sie Ihr eigenes Dokument hoch.
2. Lesen Sie das Ergebnis und jeden Prüfschritt. Eine Dienststörung ist keine ungültige Rechnung.
3. Folgen Sie, wo vorhanden, einer Regelerläuterung, korrigieren Sie Ihr Quelldokument und validieren Sie es erneut.

Peppol-Validator öffnenVollständige Beispielrechnung ansehen

Weitere Formate: XRechnung oder ZUGFeRD / Factur-X, beide auf Deutsch und Englisch. Der Peppol-Validator lädt das Ergebnis außerdem als JSON und als lesbaren Bericht herunter, den Sie drucken oder als PDF speichern können.

Das Beispiel einer Peppol-XML-Rechnung geht ein gültiges Beispiel Feld für Feld durch, gleicht seine Summen ab und zeigt eine fehlerhafte Kopie mit ihren zwei Befunden und der Korrektur. Um eine Rechnung zu lesen, statt sie zu prüfen, öffnet der kostenlose XML-Rechnungs-Viewer eine UBL-Rechnung oder -Gutschrift als lesbares Dokument, und der XRechnung-Viewer tut dasselbe für XRechnung in UBL oder CII.

Aus Ihrem Code validieren

Dieser Schnellstart validiert die veröffentlichte Beispielrechnung nach Peppol BIS Billing 3 über Version 2 der Finance API und bewahrt das Ergebnis auf. Sie brauchen bash, curl und sha256sum sowie ein kostenloses Ironfang-Konto.

1. Einen API-Schlüssel mit Berechtigung erstellen

Öffnen Sie im Portal (auf Englisch) Developers, API keys und erstellen Sie einen Schlüssel mit der Berechtigung Validate and generate e-invoices, finance:einvoices:write. Das Geheimnis wird nur einmal angezeigt. Bewahren Sie es in der Umgebungsvariablen IRONFANG_API_KEY auf, nie in einem Skript oder Repository. Noch kein Konto? Erstellen Sie ein kostenloses.

2. Die Beispielrechnung herunterladen

Die Beispielrechnung ist eine vollständige, fiktive Rechnung nach Peppol BIS Billing 3 in UBL, dieselbe, die der Peppol-Validator anbietet:

curl --fail --silent --show-error --output invoice.xml https://ironfang.uk/samples/peppol-bis-billing-3-invoice-v1.xml

3. Validieren

Speichern Sie dieses Skript als validate-peppol.sh und führen Sie bash validate-peppol.sh invoice.xml aus. Es nennt die Familie, sodass ein Dokument, das eine andere angibt, abgelehnt statt als etwas anderes geprüft wird, und es leitet den Idempotency-Key aus der Datei ab, sodass eine Wiederholung das erste Ergebnis liefert und nicht erneut berechnet wird.

#!/usr/bin/env bash
# Validate one Peppol BIS Billing 3 invoice with the Ironfang Finance API
# (V2) and keep the result.
#
#   IRONFANG_API_KEY=... ./validate-peppol.sh invoice.xml
#
# The result is written to result.json. A completed validation exits 0 and
# prints its outcome, valid or invalid. A request or service problem exits
# non-zero and leaves the Problem in result.json. A retry with the same file
# sends the same Idempotency-Key, so it returns the first result and is not
# charged again.
set -euo pipefail
file="$1"
base="${IRONFANG_FINANCE_API:-https://api.ironfang.uk/finance}"
key="peppol-$(sha256sum "$file" | cut -c1-40)"

curl --fail-with-body --silent --show-error \
  "$base/v2/einvoices/validate?family=peppol-bis-billing-3" \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: $key" \
  --data-binary "@$file" \
  --output result.json

grep -o '"outcome":"[a-z]*"' result.json | head -n 1

4. Die Antwort lesen

Das Skript gibt "outcome":"valid" aus und bewahrt das vollständige Ergebnis in result.json auf. Gekürzt, ohne Engines und Zeitangaben:

{
  "schema": "ironfang/finance/einvoice/validation-result/v2",
  "operation_id": "01929a8e-0000-7000-8000-000000000000",
  "status": "completed",
  "outcome": "valid",
  "input": {
    "media_type": "application/xml",
    "document_type": "invoice"
  },
  "ruleset": {
    "requested": "latest",
    "id": "fwrs_pub_invoice_2026_5",
    "family": "peppol-bis-billing-3",
    "selection_method": "latest",
    "official_release": "2026.5 (May 2026 release, aka BIS Billing 3.0.21)"
  },
  "coverage": {"scope": "xml", "checked": ["input", "xml", "xsd", "en16931", "peppol"], "not_checked": []},
  "layers": [
    {"layer": "input", "status": "passed", "fatal": 0, "warning": 0, "information": 0},
    {"layer": "xml", "status": "passed", "fatal": 0, "warning": 0, "information": 0},
    {"layer": "xsd", "status": "passed", "fatal": 0, "warning": 0, "information": 0},
    {"layer": "en16931", "status": "passed", "fatal": 0, "warning": 0, "information": 0},
    {"layer": "peppol", "status": "passed", "fatal": 0, "warning": 0, "information": 0}
  ],
  "counts": {"by_severity": {"fatal": 0, "warning": 0, "information": 0}},
  "findings": [],
  "usage": {"charged": true, "credits": 1}
}

ruleset nennt das genaue Release, das das Dokument geprüft hat, layers meldet jede Prüfung der Reihe nach, und usage zeigt die eine Validierung, die Ihrem Kontingent angerechnet wurde. Ein Ergebnis mit Anmeldung wird 30 Tage unter GET /finance/v2/einvoices/results/{id} aufbewahrt, wobei die ID seine operation_id ist.

Gültig, ungültig oder kein Ergebnis

• Gültig: HTTP 200, status completed, outcome valid. Warnungen können trotzdem aufgeführt sein; sie lassen ein Dokument nie durchfallen.
• Ungültig: HTTP 200, status completed, outcome invalid. Jeder Eintrag in findings nennt Regel-ID, Prüfschritt, Schweregrad und Fundstelle, und counts.by_severity.fatal ist größer als null. Korrigieren Sie das Quelldokument und validieren Sie erneut; die Regelreferenz erklärt die häufigen Regeln.
• Kein Ergebnis: Jeder andere Status ist ein Problem (application/problem+json) mit einem code. Das Skript endet mit einem Exit-Code ungleich null und bewahrt das Problem in result.json auf. Ein 4xx betrifft die Anfrage oder das Konto, etwa den Schlüssel, die Größe, die Familie oder den Dokumenttyp: Beheben Sie die Ursache vor einer Wiederholung, oder warten Sie bei einem 429, bis die Begrenzung aufgehoben ist. validator_unavailable, validation_timeout und internal_error tragen outcome indeterminate: Es wurde nichts festgestellt, nichts berechnet, und dieselbe Anfrage kann wiederholt werden.

Wie es weitergeht

XRechnung und ZUGFeRD / Factur-X nutzen dieselbe Route mit ihrer eigenen Familie: Der API-Abschnitt zu XRechnung und der API-Abschnitt zu ZUGFeRD / Factur-X haben jeweils ein getestetes Skript, das für ZUGFeRD für PDFs ebenso wie für XML. Der OpenAPI-Vertrag von V2 enthält jeden Parameter und jedes Feld, und die API-Referenz weiter unten nennt die Berechtigungen und Endpunkte.

Ergebnisse und Regeln

Ein Ergebnis meldet jeden Prüfschritt der Reihe nach. Scheitert eine Voraussetzung, werden die späteren Prüfschritte übersprungen statt als bestanden gewertet. Nur fatale Befunde lassen ein Dokument durchfallen; Warnungen bleiben sichtbar, auch wenn das Ergebnis gültig ist. Über die Gültigkeit entscheiden die offiziellen Regeln, und die Validierung repariert Ihr XML nie.

Die Referenz der Validierungsregeln erklärt 142 Regeln auf je einer Seite: was fehlgeschlagen ist, die wahrscheinlichen Ursachen, die Korrektur und ein Vorher und Nachher aus Dokumenten, die dieselbe Engine wie der Validator geprüft hat. Suchen Sie eine Regel über ihren Code, einen Business Term wie BT-106 oder ein XML-Element. Regeln ohne Erläuterung behalten den Befund und die Kennung der Engine; Befunde im Validator verlinken auf eine Erläuterung, wo immer es eine gibt.

Einige Einstiegspunkte:

• BR-01: Die Spezifikationskennung fehlt

  Invoice- und CreditNote-Dokumente benötigen ein nicht leeres CustomizationID-Element, das ihre Spezifikation angibt.

• BR-CO-10: Die Positionsbeträge ergeben nicht die Summe

  Die Summe der Positionen auf Dokumentenebene muss der Summe der einzelnen Nettobeträge der Positionen entsprechen.

• BR-CO-13: Die Summe ohne Umsatzsteuer ist nicht stimmig

  Die Summe ohne Umsatzsteuer geht von der Positionssumme aus, zieht die Nachlässe auf Dokumentenebene ab und addiert die Zuschläge auf Dokumentenebene.

• BR-S-08: Der Steuerbasisbetrag zum Normalsatz passt nicht zum Dokument

  Für jeden Normalsatz muss der Steuerbasisbetrag der Aufschlüsselung den Positionsbeträgen zum Normalsatz plus Zuschlägen minus Nachlässen auf Dokumentenebene zu diesem Satz entsprechen.

• PEPPOL-EN16931-R004: Die Billing-Spezifikationskennung prüfen

  Diese Regel prüft das Präfix der Peppol-Billing-Kennung und lehnt eine Folge von zwei Doppelpunkten in der Kennung ab.

• PEPPOL-EN16931-R020: Elektronische Adresse des Verkäufers ergänzen

  Das Party-Element des Verkäufers muss ein EndpointID enthalten. Diese Regel prüft, ob es vorhanden ist; Schema und Wert prüfen andere Regeln.

• PEPPOL-EN16931-R120: Nettobetrag der Position passt nicht zu Menge und Preis

  Jeder Nettobetrag einer Position muss Menge mal Nettopreis geteilt durch Basismenge des Preises sein, plus Zuschläge der Position, minus Nachlässe der Position, mit einer Toleranz von 0.02.

• FW-XML-001: Das XML konnte nicht sicher gelesen werden

  Das Dokument enthält fehlerhaftes XML, eine nicht unterstützte Kodierung oder ein verbotenes XML-Konstrukt. Kein späterer Prüfschritt kann laufen, bis das behoben ist.

Über eine Validierung hinaus

Sobald die Validierung aus Ihrem Code läuft, bauen diese Funktionen darauf auf.

Erzeugung

Die Erzeugung erstellt Peppol BIS Billing 3 UBL, eine Rechnung oder eine Gutschrift, aus strukturiertem JSON im Format generation-input/v1. Sie erstellt keine Dokumente nach XRechnung oder ZUGFeRD / Factur-X. Die exakten endgültigen Bytes müssen den gewählten Produktionsvalidator bestehen, bevor sie zurückgegeben werden, base64-kodiert mit ihrem SHA-256; bei einem Fehlschlag wird keine Rechnung zurückgegeben, und Ironfang Finance umgeht nie eine Regel, damit eine Rechnung besteht. Mit dem JSON-Playground für Rechnungen probieren Sie es im Browser aus, und der Leitfaden zur Erzeugung enthält das Schema und vier ausführbare Schnellstarts. Die Erzeugung über ein Konto erfordert einen bezahlten Tarif.

Jobs und Batches

Job- und Batch-Endpunkte nehmen Validierungen oder Erzeugungen mit einem Schreibschlüssel für Ironfang Finance an, geben eine Job-ID zum Abfragen zurück und behalten das gewählte Regelwerk über Wiederholungen hinweg bei. Leseschlüssel rufen Metadaten und abgeschlossene Ergebnisse ab. Ein Abbruch behält bereits abgeschlossene Arbeit. Eine abgeschlossene Validierung ist gültig oder ungültig; Dienststörungen bleiben ohne Ergebnis (indeterminate) und werden nicht berechnet. Dauerhafte Jobs nutzen dieselben Engines, versenden keine Rechnungen und fügen keine rechtliche Zertifizierung hinzu.

Webhooks und Zustellung

Konten können signierte Event-Webhooks und die Auslieferung von Artefakten an S3-kompatiblen Speicher als getrennte Ziele einrichten. Jedes Ziel hat seinen eigenen Verlauf der Wiederholungen; eine fehlgeschlagene Zustellung ändert kein Ergebnis und führt nicht zur Berechnung einer weiteren Validierung. Prüfen Sie Webhook-Signaturen und deduplizieren Sie Event-Kennungen bei Ihrem Empfänger.

Die S3-Qualifizierung umfasst SeaweedFS 4.46 in der getesteten Konfiguration; andere Anbieter brauchen eigene Prüfungen. PDFs und ZIP-Dateien signierter Berichte werden nicht automatisch exportiert. Die Zustellung an Ihren Endpunkt oder Bucket belegt weder die Annahme durch den Empfänger noch die Übernahme in die Buchhaltung oder die Zahlung, und sie versendet die Rechnung nicht über Peppol.

Gespeicherte Ergebnisse und Datenschutz

Anonyme Dokumente und Ergebnisse werden nur flüchtig verarbeitet. Mit Anmeldung oder API-Schlüssel werden Ergebnis-JSON und Befunde 30 Tage gespeichert, und Sie können sie früher löschen. Die synchrone Validierung bewahrt das hochgeladene Dokument nicht auf. Dauerhafte API-Jobs bewahren die verschlüsselte Eingabe bis zum Abschluss, zum Abbruch oder zur Bereinigung nach Ablauf von 24 Stunden auf. Sicherungen folgen ihrer eigenen Aufbewahrungsrichtlinie. Mit Anmeldung erzeugtes XML wird mit seinem Ergebnis 30 Tage aufbewahrt. Heruntergeladene Kopien bleiben unter Ihrer Kontrolle.

Nach dem Löschen oder Ablauf bewahrt ein kleiner Vorgangsdatensatz Hashes, Regelwerk, Prüfausgang, Zeitstempel und Nutzungsmetadaten bis zur Löschung der Organisation auf. So kann eine alte Wiederholung weder erneut laufen noch erneut berechnet werden: Wer ihren Idempotency-Key wiederverwendet, erhält 410 result_gone. Fordern Sie eine neue Validierung mit einem neuen Idempotency-Key also nur an, wenn Sie das wirklich wollen. Signierte Berichte machen aus einem gespeicherten Ergebnis einen überprüfbaren Nachweis.

Peppol-Validierungspipeline

So wird ein Dokument nach Peppol BIS Billing 3 geprüft. UBL ist die Syntax des XML-Dokuments, EN 16931 definiert die Kernsemantik einer elektronischen Rechnung, und Peppol BIS Billing ergänzt seine Nutzungsregeln. Ironfang Finance sendet die übergebenen XML-Bytes an seinen selbst betriebenen Java-Dienst, in dem PHIVE die registrierten Validierungsartefakte der Herausgeber ausführt und für deren XSLT-Prüfungen Saxon nutzt. XRechnung und ZUGFeRD / Factur-X durchlaufen ihre eigenen Prüfschritte, die in ihren Leitfäden aufgeführt sind.

1. Wohlgeformtheit des XML: Das Dokument muss sich sicher parsen lassen. Fehlerhaftes XML ist etwas anderes als ein Verstoß gegen eine Geschäftsregel.
2. UBL-Schema: Invoice oder CreditNote muss die Struktur und die Datentypen haben, die ihr UBL-Schema definiert.
3. EN 16931: Die Artefakte der Herausgeber prüfen die anwendbaren Semantik- und Berechnungsregeln.
4. Peppol: Die BIS-Billing-Artefakte der Herausgeber prüfen die anwendbaren Profil- und Nutzungsregeln.
5. Dienststörungen: Zeitüberschreitungen, nicht verfügbare Validatoren und interne Fehler bleiben ohne Ergebnis. Sie stellen nicht fest, ob die Rechnung gültig ist.

Welche Versionen haben mein Dokument geprüft?

Jedes Ergebnis nennt sein genaues Regelwerk und seine Engine. Die Live-Registry der Regelwerke führt VESIDs, Dokumenttypen, Releases der Spezifikationen, Prüfsummen und Lebenszyklusdaten auf. Neuere Validatoren liefern zusätzlich ein Laufzeitobjekt mit den Versionen von Validator, PHIVE, phive-rules, phive-rules-peppol und Saxon, dem VES-Namen des Herausgebers und dem Status der Abkündigung.

Die Laufzeitmetadaten sind eine verifizierte Beobachtung zum Zeitpunkt observed_at, keine Live-Garantie der Betriebsbereitschaft. Ältere aufbewahrte Validatoren können sie weglassen. Bibliotheksversionen und Releases der Spezifikationen sind getrennte Identitäten; ein Gültigkeitsdatum des Herausgebers ist nur enthalten, wenn PHIVE eines liefert. Das Lebenszyklus-Label sendable der Registry wählt das aktive Release für latest; es bedeutet nicht, dass Ironfang Finance eine Rechnung versenden kann.

Die Standards, Regelwerke und Open-Source-Bibliotheken hinter jeder Prüfung sind mit ihren Lizenzen und dem Ort, an dem ihr Quellcode veröffentlicht ist, unter Lizenzen und Danksagungen aufgeführt.

API-Referenz

Senden Sie den Plattform-API-Schlüssel als Bearer-Token. Validieren Sie mit POST /finance/v2/einvoices/validate für jedes Format oder mit POST /finance/v1/einvoices/validate für Peppol. Validierung, Erzeugung und Löschung erfordern finance:einvoices:write; das Lesen von Ergebnissen erfordert finance:einvoices:read; authentifizierte Abfragen der Regelwerke erfordern finance:einvoices:rulesets:read. V1 listet seine Ergebnisse unter /finance/v1/einvoices/results auf und liest oder löscht eines über die Vorgangs-ID; V2 listet Ergebnisse von V1 und V2 gemeinsam auf, wie der Leitfaden zu V1 und V2 erklärt. Der Ironfang MCP-Server bietet 3 Tools für Ironfang Finance. Nur Referenz: was eine Validierungsregel bedeutet und wie man sie behebt, und welche Regelwerke der Validator ausführt. Validierung und Erzeugung von Dokumenten, Ergebnisse und Jobs gibt es nur über REST; die Ironfang Finance API nimmt einen Plattform-API-Schlüssel an und hat noch keine OAuth-Delegation.

OpenAPI-Vertrag V2 - OpenAPI-Vertrag V1 - API-Schlüssel und Integrationsbeispiele - Datenschutzerklärung

In Postman ausführenCollection ansehen

Die Collection wird aus dem OpenAPI-Vertrag erzeugt und beginnt mit drei Anfragen, die keine Zugangsdaten brauchen: die Regelwerke auflisten, eine Beispielrechnung validieren und eine aus JSON erzeugen. Sie können sie auch herunterladen. Bewahren Sie API-Schlüssel in einer privaten Umgebung oder einem Tresor auf, und wählen Sie die Rechnungsdateien aus, die Sie wirklich senden wollen.

SDKs und Tarife

SDKs, CLI und GitHub Action

Die Validierungs-SDKs für Python und TypeScript, eine Python-CLI und die offizielle GitHub Action sind öffentlich als v0.2.0 veröffentlicht. Sie decken die Validierung von Invoice und CreditNote gegen ein gewähltes Regelwerk über V1 ab, und über V2 Peppol BIS Billing 3, XRechnung und ZUGFeRD / Factur-X als XML oder hybrides PDF, mit Jobs, Batches und Zustellungen von V2 und getrennten Ergebnissen für gültige Dokumente, ungültige Dokumente und Dienststörungen. Installationsanleitungen und die fixierte öffentliche Referenz der Action finden Sie im Integrationsleitfaden (auf Englisch). Installieren Sie TypeScript über npm, oder laden Sie das Python-Release von GitHub herunter.

Kostenlose und bezahlte Tarife

Kostenlose Konten enthalten 250 Validierungen pro UTC-Kalendermonat, ohne Karte. Die Erzeugung mit Anmeldung erfordert ein bezahltes Abonnement Build, Pro oder Platform. Bezahlte Tarife teilen ein Kontingent zwischen Validierung und Erzeugung, das dem monatlichen Abonnementzeitraum folgt. Vergleichen Sie die aktuellen Preise und Kontingente.

Bezahlte Tarife richten sich an Unternehmen im Vereinigten Königreich und in der EU, einschließlich Einzelunternehmern. Eine britische VAT-Nummer ist optional. Der automatische Checkout in der EU erfordert eine verifizierte USt-IdNr. und übereinstimmende Unternehmensdaten; Unternehmen ohne USt-IdNr. oder mit verifizierten Daten, die geprüft werden müssen, brauchen vor der Zahlung eine Freigabe. Geben Sie Ihre Unternehmensdaten ein, beantragen Sie die Prüfung und wählen Sie einen Tarif im Abrechnungsportal (auf Englisch).

Eine abgeschlossene Validierung zählt auch dann, wenn sie Fehler in der Rechnung findet; eine erfolgreiche Erzeugung zählt einmal. Noch nicht abgeschlossene Arbeit reserviert Kontingent. Downloads und idempotente Wiederholungen verursachen keine Nutzung. Fehlerhafte Anfragen und Dienststörungen verbrauchen kein Kontingent. Die Obergrenze stoppt neue Kontovorgänge, bis Kapazität frei wird, Ihr Zeitraum sich erneuert oder Sie Ihren Tarif erhöhen; es gibt keine automatischen Mehrkosten.

Die anonymen Validatoren und der JSON-Playground bleiben kostenlos, mit Anfrage- und Ratenbegrenzungen. Anonyme Nutzung hat keinen gespeicherten Verlauf und kein Kontingent eines Kontos. Abonnements, Zahlungsdaten und Rechnungsverlauf von Ironfang Finance sind von Ironfang Render und Ironfang Audit getrennt.

Anfragelimits

XML und JSON für die Erzeugung sind auf 5 MiB begrenzt, und eine XML-Validierung hat eine Frist von 10 Sekunden. Ein hybrides PDF hat eigene, höhere Limits und eine längere Frist, beschrieben im Leitfaden zu ZUGFeRD / Factur-X. Ein Ergebnis liefert höchstens 1.000 Befunde direkt mit: Prüfen Sie die Befundzahlen und die Hinweise auf Kürzung, denn eine gekürzte Liste ist keine vollständige Prüfung. Ratenbegrenzungen liefern HTTP 429; beachten Sie Retry-After, wenn es angegeben ist. Die OpenAPI-Verträge enthalten die Limits für Eingaben und Felder.

Was ein gültiges Ergebnis nicht belegt

• Es übermittelt die Rechnung nicht über das Peppol-Netzwerk.
• Es macht Ironfang nicht zu einem Peppol Access Point.
• Es registriert keinen Peppol-Teilnehmer und weist dessen Registrierung nicht nach.
• Es bescheinigt keine rechtliche oder steuerliche Konformität.
• Es garantiert nicht, dass ein Empfänger die Rechnung annimmt, verbucht oder bezahlt.

Ein gültiges Ergebnis bedeutet, dass diese Bytes das gewählte unterstützte Regelwerk bestanden haben. Anforderungen des Empfängers, der geschäftliche Kontext und rechtliche oder steuerliche Fragen erfordern eine gesonderte Prüfung.