The KSeF FA(3) Schema: What Changed and What It Means for Your Mapping

KSeF checks every invoice against its schema. An invoice built for the wrong structure gets rejected; there is no partial acceptance. If your ERP output, EDI translation or document-capture flow still produces FA(2) XML, it now produces invoices that cannot be issued in Poland.

This post is for finance analysts, ERP analysts and integration owners. It covers what changed in the KSeF FA(3) schema, which changes affect mapping logic, and where projects tend to slip.

What the KSeF FA(3) schema is and why it replaced FA(2)

FA(3) and mandatory KSeF

FA(3) is the logical XML structure for structured invoices in KSeF 2.0. KSeF 1.0 was launched as a voluntary system, while KSeF 2.0 is the new mandatory version from February 2026, built on FA(3) and a completely new API specification. The schema change and the API change arrived together, so integration teams had to handle both.

Timeline and transition rules

According to the Ministry of Finance, the FA(3) structure applies from 1 February 2026. Since 1 April, most companies have been required to use KSeF.

One transition rule matters for mapping. Corrective invoices for originals issued in FA(2) up to 31 January 2026, and settlement invoices for advance invoices issued in FA(2) in that period, must be issued using the new schema. Your correction logic therefore has to reference FA(2) originals while producing FA(3) output.

What changed in the ksef fa(3) schema

The overall build of the schema and its field types did not change. The header, parties, invoice body and footer are all still there. The changes sit inside those blocks, which makes them easy to underestimate.

Header and versioning

The Ministry’s comparison document shows the system code moving from FA (2) to FA (3) and the form variant from 2 to 3. This is a one-line change, and a hardcoded FA(2) header fails validation immediately.

Parties: JST, GV and new Podmiot3 roles

This is the largest change for buyer-side mapping. Podmiot2 now carries markers showing whether the invoice relates (“1”) or does not relate (“2”) to a subordinate local-government unit (JST) or a VAT group member (GV). Where “1” is used, the Podmiot3 section should be completed, including the third party’s NIP or internal ID.

The Ministry also lists a new Podmiot3 role for employees, which helps identify employee expenses, along with a longer P_7 field for the goods or service name.

Attachments

A new Zalacznik element lets supporting documents be attached directly to an invoice in KSeF. For analysts, this means deciding which data currently travels as a PDF annex and whether it should move into the structured invoice.

VAT rates, payment and corrections

The other changes analysts need to track:

• The dictionary of VAT rate values is significantly extended.

• The partial payment marker now separates “partially paid” from “fully paid in instalments”.

• The number of corrected-invoice records (DaneFaKorygowanej) is capped at 50,000.

The HubBroker e-invoicing platform handles schema versions like these in the mapping layer rather than in the ERP.

What it means for your mapping

Source data your ERP may not hold

The new markers need data that many ERPs don’t store as fields. Examples include whether a buyer is a JST unit or a VAT group member, the internal ID of the recipient unit, and an employee identifier for expense invoices. If the data isn’t in the ERP, no mapping can produce it. Start with a master-data gap list, not with XSLT.

Address data also needs a check. The FA(3) structure requires the address in the AdresL1 field, contrary to the common view that only the NIP matters in KSeF.

Logic that needs rework

Three areas usually need new logic, not just field renames:

• Corrections. The optional Podmiot1K element carries corrected seller data when the original invoice contained errors, and Podmiot2K does the same for the buyer. Where there are additional buyers, each one in the original needs a matching correction block.

• Advance and settlement invoices that cross the FA(2)/FA(3) boundary.

• Multi-party invoices, where Podmiot3 roles now carry business meaning.

For SAP Business One, Dynamics 365 Business Central and other ERPs, these rules belong in a mapping layer between the ERP and KSeF. That avoids custom code inside the ERP.

Test before cutover

The Ministry released the KSeF 2.0 API test environment on 30 September 2025, along with .NET and Java integration libraries. Test the edge cases (JST buyers, corrections of FA(2) originals, attachments, partial payments), not only a standard invoice.

Where mapping projects go wrong

• Treating FA(3) as a version bump. The header change takes minutes. The party and correction logic takes weeks.

• Mapping before the data audit. Teams build XSLT for JST markers and then find the ERP has no field to feed them.

• Testing only the happy path. Standard invoices pass. Corrections and multi-party invoices are where KSeF rejects documents.

• Ignoring inbound. Your AP team now receives FA(3) invoices with attachments and Podmiot3 data. Capture flows and PDF-to-XML conversion for non-KSeF suppliers need to land in the same posting logic.

Keeping FA(3) changes out of your ERP

Schemas will keep changing. FA(3) will not be the last version. If every change means an ERP development project, each new version becomes a budget discussion. An integration layer holds the KSeF mapping, validation and API connection, while your ERP keeps producing the data it already produces. When the schema changes again, the change happens in one place.

For the wider sequence from assessment to production monitoring, see our e-invoicing implementation roadmap.

FAQ

Is FA(2) still accepted in KSeF?
No. FA(3) applies from 1 February 2026. Corrections of FA(2) originals are also issued in FA(3).

Does FA(3) change the overall invoice structure?
No. The main blocks are the same. The changes are inside them: party markers, roles, VAT codes, payment fields, correction elements and attachments.

Do I need new data in my ERP?
Often, yes, especially for JST and VAT-group buyers, employee expenses and attachments. Run a master-data gap check first.

Can FA(2) output be converted to FA(3) automatically?
The header and renamed fields can be. New markers and roles cannot, unless the source data exists.

Where is the official FA(3) XSD?
On the Ministry of Finance KSeF portal which also publishes the FA(2) to FA(3) comparison document.

Planning an FA(3) mapping review? HubBroker can run a gap check of your current KSeF output against the FA(3) schema, covering both data and logic. Book a conversation with our integration team.