XRechnung & ZUGFeRD Invoice Validator API

Validate XRechnung XML and ZUGFeRD or Factur-X XML/PDF invoices through one API. Every evaluated invoice receives a deterministic technical assessment, structured findings, SHA-256 evidence, and the exact pinned rule versions.

Technical validation only. ACCEPTED means every required validation layer accepted the submitted invoice. It does not establish legal or tax validity, authenticity, successful delivery, visible PDF versus XML equality, or recipient acceptance.

What is validated

Input	Required checks
XRechnung XML	KoSIT Validator 1.6.0 with XRechnung configuration v2026-01-31
ZUGFeRD or Factur-X CII XML	Exact profile allowlist, ZUGFeRD 2.5 XSD, and profile Schematron
ZUGFeRD or Factur-X PDF	PDF/A-3 with veraPDF, safe embedded XML extraction, XMP and attachment consistency, then the complete CII XML checks

The hybrid PDF result is accepted only when all required layers pass. PDF/A compliance alone is never treated as a valid invoice.

Supported ZUGFeRD and Factur-X profiles:

• MINIMUM
• BASIC_WL
• BASIC
• EN16931
• EXTENDED

Legacy ZUGFeRD 2.0 guideline identifiers are recognized as their matching profiles and validated against the same pinned rule set; this recognition is an explicit allowlist entry, not a fuzzy match.

XRechnung CII remains on the pinned KoSIT path. Unsupported or lookalike guideline identifiers are not silently mapped to a profile.

Quick start

The default input validates an official XRechnung sample:

{
  "documents": [
    {
      "documentId": "xrechnung-sample",
      "fileName": "01.01a-INVOICE_ubl.xml",
      "url": "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/v2026-01-31/src/test/business-cases/standard/01.01a-INVOICE_ubl.xml"
    }
  ],
  "resultDetail": "FINDINGS",
  "maxFindingsPerDocument": 100,
  "storeXmlReport": false,
  "storeHtmlReport": false,
  "storePdfaReport": false,
  "storeExtractedInvoiceXml": false
}

Send a hybrid invoice as an HTTPS URL or base64:

{
  "documents": [
    {
      "documentId": "supplier-invoice-1042",
      "fileName": "supplier-invoice-1042.pdf",
      "url": "https://example.com/signed/invoice-1042.pdf"
    }
  ],
  "resultDetail": "FINDINGS"
}

Each documents item must contain exactly one source field: url, xml, or base64. Console file upload and customer key-value store records are also supported.

The input and output schemas are agent-readable and work with the Apify API, MCP clients, Make, n8n, webhooks, and standard SDKs.

Output

One dataset item is returned for every submitted entry. A technically rejected invoice is a successful validation, not a processing failure.

The two records below are verbatim field subsets from live Apify run R9gep9fAWMbrVA96h on build 0.0.9, executed on 2026-07-29. Omitted fields were not reconstructed.

This Actor is also exposed to AI agents through Apify's MCP server (mcp.apify.com): an agent can discover it by search and run it with the same pay-per-event billing, with no separate integration.

Pricing

• invoice-validated: $0.004 for each invoice that produces an ACCEPTED or REJECTED result
• apify-actor-start: $0.00005 per GB of Actor memory, charged automatically when a run starts, with a minimum of one event

NOT_EVALUATED processing failures do not trigger the invoice validation event. The Actor start charge still applies.

Result semantics

Processing	Conformance	Meaning	Charged validation event
SUCCEEDED	ACCEPTED	Every required pinned technical layer passed	Yes
SUCCEEDED	REJECTED	The invoice was evaluated and one or more required rules failed	Yes
FAILED	NOT_EVALUATED	Source, format, engine, timeout, report, or budget failure prevented a decision	No

When pay-per-event pricing is active, only evaluated rows use the invoice-validated event. Processing failures are not charged.

Optional reports

All optional records are off by default:

• storeXmlReport: KoSIT report or normalized ZUGFeRD XSD and Schematron report
• storeHtmlReport: human-readable validation report
• storePdfaReport: sanitized veraPDF XML report for hybrid PDFs
• storeExtractedInvoiceXml: complete XML extracted from a hybrid PDF

Returned report keys appear in the row's reports object. Raw reports and extracted XML can contain invoice data and follow the retention settings of the customer's Apify account.

Security and limits

• Validation runs locally inside the Actor container.
• No invoice is sent to a third-party validation API.
• Raw invoice content is not copied to the output dataset or logs.
• HTTPS downloads block private, local, reserved, and cloud metadata targets.
• DTDs, entities, and external XML resources are blocked.
• PDF parsing runs in an isolated process with CPU, memory, file, and descriptor limits.
• XML Schema validation runs in a separate isolated process.
• Java validation stages have timeouts and bounded reports.
• Each XML is limited to 5 MiB.
• Each PDF is limited to 20 MiB and 100 pages.
• Each PDF can expose at most 16 unique embedded file specifications.
• A run can evaluate up to 100 XML invoices, up to 20 PDF invoices, and 100 MiB total input.
• Finding fields and the total returned findings payload are bounded.

Validation findings can quote an offending invoice value. Treat results and optional reports as sensitive invoice data.

Pinned stack

Component	Version
KoSIT Validator	1.6.0
XRechnung configuration	v2026-01-31
XRechnung	3.0.2
CEN Schematron	1.3.15
ZUGFeRD rules	2.5
Factur-X rules	1.09
Mustangproject rule bundle and Saxon runtime	2.24.0
veraPDF	1.30.2

Docker builds verify downloaded engines against fixed SHA-256 checksums. ZUGFeRD decisions come from the release-pinned profile XSD and Schematron assets directly, avoiding unrelated wrapper heuristics.

Release gates

The release suite covers:

• Official XRechnung accepted and rejected UBL/CII fixtures
• All 51 current FeRD ZUGFeRD 2.5 example PDF/XML pairs
• BASIC, EN16931, and EXTENDED official examples
• MINIMUM and BASIC_WL compatibility fixtures
• PDF/A failure, XML Schema failure, Schematron failure, malformed XMP, ambiguous attachments, and digest consistency negatives

Official FeRD fixtures are downloaded only for release testing and are not redistributed in the production image.

Current scope

This Actor does not verify:

• Whether visible PDF text equals the embedded XML
• Digital signatures or issuer authenticity
• Peppol delivery or recipient portal acceptance
• Tax treatment, legal validity, fraud, duplicates, or payment approval
• ZUGFeRD 1.x, generic CIUS, or EXTENDED-CTC-FR

Common processing error codes

• DOCUMENT_LIMIT_EXCEEDED
• PDF_RUN_LIMIT_REACHED
• SOURCE_FETCH_FAILED
• SOURCE_HTTP_ERROR
• SOURCE_TOO_LARGE
• UNSUPPORTED_MEDIA_TYPE
• PDF_MAGIC_INVALID
• PDF_ENCRYPTED
• XML_MALFORMED
• DOCTYPE_FORBIDDEN
• NO_SCENARIO_MATCH
• VALIDATION_TIMEOUT
• REPORT_PARSE_FAILED
• REPORT_TOO_LARGE
• VALIDATOR_EXECUTION_FAILED
• BUDGET_LIMIT_REACHED
• RUN_TIME_BUDGET_REACHED

Rule failures remain in findings and produce REJECTED; they are not converted into processing errors.

Official references

• KoSIT Validator
• XRechnung validator configuration
• XRechnung test suite
• ZUGFeRD 2.5 and Factur-X 1.09
• veraPDF validation documentation
• THIRD_PARTY_NOTICES.md

E-invoice validator family

Same engine, same output contract, one validator per market: Peppol BIS Billing | Poland KSeF FA(3) | France E-Invoice | Italy FatturaPA