Poland KSeF FA(3) Preflight Validator - e-Faktura XML

Catch KSeF FA(3) XML errors before opening a submission session. The Actor returns one stable, agent-readable result per invoice with official XSD findings, documented offline technical checks, exact rule versions, and SHA-256 evidence.

Technical preflight only. ACCEPTED does not establish legal or tax validity, KSeF authorization, correct encryption or session metadata, uniqueness in KSeF, successful submission, KSeF number assignment, or recipient acceptance.

Run the live Actor

What is checked

Layer	Pinned check
Structure	Official KSeF FA(3) v1-0E XML Schema
XML transport	UTF-8, no BOM, no processing instructions, KSeF prohibited Unicode ranges
KSeF limits	Document size with and without FA(3) attachments
Production identifiers	Polish NIP checksum and the NIP prefix in a Podmiot3 internal ID
Submission date	P_1 is not later than the validation date
Batch integrity	Duplicate NrWierszaFa line numbers are rejected
ERP consistency diagnostics	Line arithmetic, P_15 header totals, VAT plausibility when the rate is unambiguous, PLN conversion fields, settlement sums, and period ordering

The rule package is downloaded during the build from the official Ministry of Finance GitHub organization at commit 1c34fe2799387d517b83a2fb21e31e83d5f66247. Its archive and individual XSD files are SHA-256 verified. The patched offline main XSD also has its own manifest hash and is verified again before use. Runtime validation never downloads rules.

The ERP consistency layer returns WARNING findings because these checks are useful before submission but are not documented as KSeF server rejection rules. Official XSD and documented KSeF technical failures remain ERROR findings and produce REJECTED.

Quick start

Run with no document source to validate the built-in accepted FA(3) fixture:

{
  "resultDetail": "FINDINGS",
  "maxFindingsPerDocument": 100,
  "storeXmlReport": false,
  "storeHtmlReport": false
}

Each document can use exactly one source:

• Console file upload
• HTTPS URL with public-IP and redirect enforcement
• Inline XML
• Base64 XML
• A record in your Apify key-value store

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

Structured results

Every input produces one dataset item. A technically invalid invoice is a successful evaluation with conformanceStatus: REJECTED. A source or engine failure is NOT_EVALUATED.

These compact examples are taken from a real three-document Actor run. Every row also returns externalStateStatus: NOT_EVALUATED_EXTERNAL_STATE because KSeF authorization, session, submission, and final system state are outside offline preflight.

Billing

The invoice-validated event costs $0.004.

• ACCEPTED: billed once
• REJECTED: billed once
• NOT_EVALUATED: free
• Dataset delivery does not add a second charge
• The Actor stops before processing unless the event price is exactly $0.004

One malformed or unavailable source does not kill the remaining batch.

Release gates

Every build must pass:

1. The SHA-pinned official FA(3) XSD published by the Polish Ministry of Finance.
2. Local deterministic FA(3) acceptance and rejection fixtures for the documented technical checks.
3. Non-blocking regression fixtures for line and header arithmetic, VAT plausibility, currency conversion fields, settlement totals, and period ordering.
4. Runtime SHA-256 verification of every executed schema artifact.
5. Source, security, batch-independence, billing-guard, report, and output-contract tests.

The pinned upstream repository does not currently publish a complete official FA(3) invoice example. The regression invoices are therefore synthetic and are not described as government fixtures.

Security and privacy

• DTDs, XML entities, and external references are blocked
• HTTPS URL sources reject private, loopback, link-local, and metadata addresses
• Redirects are revalidated
• Source XML is not copied into dataset results
• Optional reports are disabled by default
• Every loaded document receives a SHA-256 digest
• The container runs as a non-root user

Important boundary

Offline validation cannot check KSeF authorization, server-side duplicate history, production availability, cryptographic session packaging, encrypted payload metadata, or the final system response. Use the official KSeF environment for the final submission decision.

For custom ERP integration or high-volume support, contact the Actor owner through the Apify profile.

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 validator family

Same engine, same output contract, one validator per market: XRechnung & ZUGFeRD (Germany) | Peppol BIS Billing | France E-Invoice | Italy FatturaPA