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.

Input options

Field	What it does	Default
invoiceFiles	Upload up to 100 FA(3) XML files in the Console	empty
documents	API documents, each with one source: url (HTTPS), xml or base64; optional documentId and fileName	built-in sample
sourceKeyValueStoreId + keyValueStoreKeys	Read FA(3) XML records from your own Apify key-value store	empty
resultDetail	FINDINGS (rule IDs, messages, locations) or SUMMARY (status and counts only)	FINDINGS
maxFindingsPerDocument	Caps the findings array; severity counts stay complete	100
storeXmlReport / storeHtmlReport	Optional reports in the run key-value store (they can contain invoice values)	false

Up to 100 invoices per run. Run with no source to validate the built-in accepted FA(3) sample.

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.

API and integrations

Validate invoices from your ERP or CI pipeline with one synchronous call. The response is the dataset of results:

curl -X POST "https://api.apify.com/v2/acts/kamerozkan~poland-ksef-preflight-validator/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documents": [{"documentId": "INV-2026-0001", "url": "https://example.com/invoices/INV-2026-0001.xml"}], "resultDetail": "SUMMARY"}'

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("kamerozkan/poland-ksef-preflight-validator").call(run_input={
    "documents": [{"documentId": "INV-2026-0001", "xml": open("INV-2026-0001.xml").read()}],
})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["documentId"], row["conformanceStatus"], row["counts"])

Gate your submission on conformanceStatus == "ACCEPTED". Make, n8n and Zapier have native Apify modules (run Actor, get dataset items), and a webhook on ACTOR.RUN.SUCCEEDED can push results into your ticketing or ERP queue.

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.

FAQ

Does this submit invoices to KSeF?

No. It is an offline technical preflight. It never logs in to KSeF, never opens a session and never sends your invoice anywhere. Use the official KSeF environment for the final submission.

Which schema version is used?

The official KSeF FA(3) v1-0E XSD from the Ministry of Finance GitHub organization, pinned to a commit and SHA-256 verified at build and at runtime.

What am I charged for?

One invoice-validated event per invoice that was actually evaluated, ACCEPTED or REJECTED. NOT_EVALUATED rows (unreadable source, fetch failure) are free. See the Billing section for the price.

Is my invoice data stored?

Source XML is not copied into the dataset. Optional XML and HTML reports are off by default. Results stay in your own Apify storage under your retention settings.

Can I validate FA(2) invoices?

No. Only FA(3), the structure KSeF uses from 2026. An FA(2) document does not pass the FA(3) schema check.

Support and feedback

• Found a wrong finding or a missing check? Open an issue on the Issues tab of this Actor with the run ID (and, if you can share it, a redacted invoice). Issues are checked every day.
• For custom ERP integration or high-volume needs, contact the Actor owner through the Apify profile.

Complete live example records (accepted, rejected, and unevaluated) with the dataset schema: sample repository.

E-invoice validator family

Same engine, same output contract, one validator per market: XRechnung & ZUGFeRD (Germany) | Peppol BIS Billing | France E-Invoice | Italy FatturaPA Parsing: ZUGFeRD & Factur-X PDF to JSON parser