ZUGFeRD & Factur-X PDF to JSON - Invoice Parser & Extractor

Extract the embedded CII invoice from a hybrid PDF and return one stable, EN 16931-oriented JSON result with technical evidence.

What it does

• Accepts up to 20 hybrid PDFs per run and 20 MiB per PDF.
• Reads uploads, inline base64, public or signed HTTPS URLs, and explicit key-value store records.
• Extracts exactly one recognized invoice attachment in an isolated worker.
• Checks PDF/A-3 identification, XMP metadata, attachment name, AFRelationship, MIME type, stream digest, and profile consistency.
• Validates MINIMUM, BASIC WL, BASIC, EN16931, and EXTENDED profile XML with release-pinned ZUGFeRD 2.5 / Factur-X 1.09 assets.
• Validates ZUGFeRD 1.0 embedded XML with pinned Mustangproject 2.24.0, then makes a digest-verified, fail-closed D16B upgrade attempt before JSON normalization.
• Normalizes available CII business terms into the shared JSON contract with EN 16931 trace entries and decimal strings.
• Can store extracted XML, validator XML, and veraPDF reports in the run key-value store.

normalizationStatus is independent from technical conformance. It is COMPLETE only when the full declared binding was transferred without unmapped evidence or converter warnings. Reduced profiles and unsupported extension semantics can return honest PARTIAL output.

For a successful ZUGFeRD 1.0 path, normalization provenance is LEGACY_ZF1_VIA_PINNED_UPGRADE. The original embedded XML remains the extractable artifact; its digest and the upgraded D16B digest are recorded separately. The legacy XSLT is not claimed to preserve every source semantic, so its integrity boundary is reported as NOT_PROVEN_BY_UPGRADER.

Product boundary

A regular PDF without embedded invoice XML is rejected. OCR is not used to guess invoice values.

The Actor does not compare visible PDF text with the embedded XML and does not verify electronic signatures. Its report is a technical assessment, not a legal-validity, tax-recognition, authenticity, or recipient-acceptance decision.

Raw XML and technical reports are opt-in KVS artifacts because they can contain invoice business data. Dataset rows contain metadata, hashes, report summaries, and normalized JSON.

Billing contract

The processing engine and Actor contract are feature-complete. The source contains a fail-closed pay-per-event charge path for document-processed at exactly $0.005 per evaluated document. Local non-PPE results remain billable: false; a hosted run stops before processing unless the event and price contract are active. The synthetic apify-actor-start event is allowed, while apify-default-dataset-item must be absent or cost USD 0.

The live Apify pricing configuration uses document-processed as the primary event. A pinned hybrid ZUGFeRD PDF hosted smoke produced one billable Dataset result and exactly one custom document charge. Source failures, NOT_EVALUATED results, runtime failures, and budget-limited documents are not eligible for the custom document charge.

Real output from a live run

Unedited record from a live run on 2026-07-30 against an official ZUGFeRD corpus PDF; long sub-objects are shortened here, values are exactly as returned:

{
  "contractVersion": "einvoice-suite-result/1.0.0",
  "actorName": "zugferd-facturx-pdf-to-json",
  "itemId": "corpus-zugferd-en16931",
  "inputIndex": 0,
  "fileName": "zugferd_2p0_EN16931_Einfach.pdf",
  "producedAt": "2026-07-30T08:40:44.866151Z",
  "processingStatus": "SUCCEEDED",
  "conformanceStatus": "ACCEPTED",
  "billable": true,
  "scope": "DOCUMENT_EXTRACTION_NORMALIZATION_AND_TECHNICAL_CHECKS",
  "source": {
    "sourceKind": "URL",
    "container": "PDF_A_3",
    "syntax": "CII_INVOICE",
    "sha256": "29842457f57143aba5da78fdf390aba773c965e60b1caab93dfff3e9d4c802f4",
    "embeddedXmlSha256": "5600027528d5ffaf89fb0be911c73ec84125a98411525e7299c7ca3a0ab073f7",
    "standard": {
      "family": "ZUGFERD",
      "profile": "ZUGFERD_EN16931",
      "scenario": "ZUGFeRD 2.5 / Factur-X 1.09 EN16931",
      "version": "2.x"
    }
  },
  "normalizationStatus": "PARTIAL",
  "report": "(report, shortened here)",
  "container": "(container, shortened here)",
  "engineDurationMs": 6533,
  "artifacts": {
    "embeddedXml": {
      "mediaType": "application/xml",
      "byteLength": 10702,
      "sha256": "5600027528d5ffaf89fb0be911c73ec84125a98411525e7299c7ca3a0ab073f7",
      "storageStatus": "NOT_REQUESTED"
    }
  },
  "invoice": "(invoice, shortened here)"
}

When the PDF is not an e-invoice

A plain, non-hybrid PDF is refused with a named error instead of a guessed result, and billable: false means it is not charged. Unedited record from a live run on 2026-07-30:

{
  "contractVersion": "einvoice-suite-result/1.0.0",
  "actorName": "zugferd-facturx-pdf-to-json",
  "itemId": "plain-pdf",
  "inputIndex": 0,
  "fileName": "plain.pdf",
  "producedAt": "2026-07-30T08:52:37.059056Z",
  "processingStatus": "FAILED",
  "conformanceStatus": "NOT_EVALUATED",
  "billable": false,
  "scope": "DOCUMENT_EXTRACTION_NORMALIZATION_AND_TECHNICAL_CHECKS",
  "error": {
    "code": "PDF_PARSE_FAILED",
    "message": "The input PDF could not be parsed safely"
  }
}

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.

E-invoice tool family

Validators, one per market, same output discipline: XRechnung & ZUGFeRD | Peppol BIS | France | Poland KSeF | Italy FatturaPA