KSeF FA(3) Invoice Generator

KSeF invoice generator for Poland: strict JSON in, a generated and technically validated KSeF FA(3) v1-0E XML invoice out.

The Actor calculates totals with decimal arithmetic, generates the FA(3) XML, validates it against the official FA(3) XSD plus offline cross-field rules, stores only accepted artifacts, and returns a SHA-256 evidence record. A rejected artifact is not delivered and not charged.

Who it is for

• Billing and ERP developers who need FA(3) XML for the Polish National e-Invoice System (KSeF) without building and maintaining the schema mapping themselves.
• Accounting tools and SaaS products that sell to Polish customers and want a pay-per-invoice generator behind an API.
• Teams migrating to mandatory KSeF who want to check their invoice data before going live.

Input

Use invoice for one document or invoices for a batch of up to 100. Amounts and quantities must be JSON strings such as "19.00", not floating-point numbers. The input schema exposes the complete production v1 canonical model and the strict KSeF extension (extensions.ksef). Unknown fields are rejected instead of being silently ignored.

Input example (the Actor's prefilled example, shortened):

{
  "invoice": {
    "invoice_number": "INV-2026-0001",
    "issue_date": "2026-07-29",
    "currency": "PLN",
    "invoice_type_code": "380",
    "seller": {"name": "Przykladowy Sprzedawca Sp. z o.o.", "vat_id": "PL5265877635", "tax_id": "5265877635",
               "address": {"line1": "ul. Prosta 1", "city": "Warszawa", "postal_code": "00-001", "country_code": "PL"}},
    "buyer": {"name": "Przykladowy Nabywca Sp. z o.o.", "vat_id": "PL1234563218", "tax_id": "1234563218",
              "address": {"line1": "ul. Dluga 2", "city": "Krakow", "postal_code": "30-001", "country_code": "PL"}},
    "lines": [{"id": "1", "description": "Usluga doradcza", "quantity": "2", "unit_code": "HUR",
               "unit_price": "500.00", "tax_rate": "23", "tax_category": "S"}],
    "payment": {"means_code": "30", "iban": "PL61109010140000071219812874"},
    "extensions": {"ksef": {"jst": false, "gv": false}}
  }
}

Production v1 capabilities

• Generate production FA(3) invoice and correction scenarios with strict country-specific options.
• Support VAT groups, foreign-currency VAT reporting, annotations, advances, payment state, order rows, and structured attachments where applicable.
• Validate the official FA(3) XSD plus deterministic offline cross-field rules.

Output

Each dataset row contains the technical assessment, artifact key, evidence key, hash, byte count, generator version, standard version, pinned ruleset, and bounded findings. The XML artifact and the evidence JSON are private key-value store records.

Field	Meaning
invoiceNumber	Your invoice number
conformanceStatus	ACCEPTED, or the reason it was not
artifactDelivered	true when the XML was stored and charged
artifactKey	Key of the FA(3) XML in the run's key-value store
evidenceKey	Key of the evidence JSON
evidence.artifactSha256	SHA-256 of the XML
evidence.validation	Validation scope, engine, counts and findings

Output example (real row from run UaeWB2BtWmBDybX0G with the example input, shortened):

{
  "inputIndex": 0,
  "invoiceNumber": "INV-2026-0001",
  "processingStatus": "SUCCEEDED",
  "conformanceStatus": "ACCEPTED",
  "artifactDelivered": true,
  "artifactKey": "ARTIFACT-0001-INV-2026-0001.xml",
  "evidenceKey": "EVIDENCE-0001.json",
  "evidence": {
    "standard": "KSeF FA(3)",
    "artifactSha256": "9117ae3f8092e2998c6fb49ff00670b9d5a0541537b8040257a47b82fb6885ef",
    "artifactBytes": 2459,
    "versions": {"generator": "1.0.0", "standard": "FA(3) v1-0E", "ruleset": "Official FA(3) XSD plus offline technical checks"},
    "validation": {"status": "ACCEPTED", "scope": "PINNED_OFFLINE_TECHNICAL_PREFLIGHT",
                   "counts": {"fatal": 0, "error": 0, "warning": 0, "information": 0}, "findings": []},
    "transmitted": false
  },
  "error": null
}

How much does it cost?

You pay $0.01 per generated invoice that passed validation and was delivered, plus the Apify Actor start event of $0.00005 (counted per GB of run memory as Apify defines it, a fraction of a cent per run). Invoices that end in NEEDS_INPUT or fail generation or validation are not charged.

Worked example: one batch run with 100 invoices costs 100 x $0.01 = $1.00 plus the start event. A single invoice in its own run costs $0.01 plus the start event. Batching up to 100 invoices per run keeps the start fee negligible.

How to generate a KSeF FA(3) invoice

1. Open the Actor and click Try for free. The example input is a complete FA(3) VAT invoice.
2. Replace seller, buyer, lines and payment with your data. Keep amounts and quantities as strings.
3. Set the KSeF options in extensions.ksef (for example jst and gv for local government units and VAT groups).
4. Click Start. Each dataset row shows ACCEPTED or the findings; the XML artifact and the evidence JSON are in the run's key-value store under the keys given in the row.
5. Submit the XML to KSeF through your own authenticated KSeF session or integrator. This Actor does not submit it.

Integrations and API

Call it from your billing system with the Apify API or the apify-client package and download the XML from the key-value store:

from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("kamerozkan/ksef-fa-invoice-generator").call(run_input={"invoices": [invoice_1, invoice_2]})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row)

curl -X POST "https://api.apify.com/v2/acts/kamerozkan~ksef-fa-invoice-generator/runs?token=<YOUR_APIFY_TOKEN>" \
  -H "Content-Type: application/json" -d @invoice.json

It also works from Make, n8n, Zapier or any HTTP client, and a webhook on ACTOR.RUN.SUCCEEDED can push the finished XML to your storage or accounting tool.

FAQ

Does it send the invoice to KSeF? No. It generates and technically checks the FA(3) XML; you submit it with your own KSeF authentication (token or certificate) or through your integrator.

Which schema version is used? KSeF FA(3) v1-0E with the official XSD pinned by SHA-256; the hash is in every evidence record.

Why must amounts be strings? To keep exact decimal arithmetic. Floating-point numbers are rejected so totals and VAT never drift by a grosz.

What happens if my input is incomplete? The row reports NEEDS_INPUT with the missing or invalid fields, and nothing is charged for that invoice.

Can I only validate an existing FA(3) XML? Use the separate Poland KSeF preflight validator Actor from the same author for XML you already have.

Is my invoice data public? No. Artifacts and evidence are stored in your run's private key-value store, and the dataset row holds only hashes, keys and findings.

Something is not working? Open an issue on the Issues tab with your run link.

Operational boundary

This Actor generates and validates the document. It does not submit to Peppol, KSeF, SdI, or a French platform. It does not authenticate to an authority, create a qualified signature, perform legal archival, assign an official network identifier, or guarantee recipient or tax-authority acceptance. ACCEPTED means the generated artifact passed the documented pinned offline technical gate.