The KSeF scheme sounds like something that should be of interest only to programmers. And then the moment comes when we need to send a document to the National E-Invoice System and suddenly it turns out that this is not about a “nice PDF”, but about data that we need to correctly arrange in a certain structure. That's what a logical structure is for. This is a description of what the e-invoice should look like, what fields are required, which are optional and what must match for the system to accept it.
On the technical side, the topic revolves around schema and FA, because they define what the data format looks like. In practice, this means that we prepare the document as XML and we must structure information such as seller data, buyer data, items, VAT rates and summaries well. If something does not agree, rejection will appear. If it is correct, we get a confirmation, that is, the UPO and the number of the KSeF as the document identifier.
In this article we will show you:
— how to understand the logical layout of data and what is the logical structure of an e-invoice
— where on the ePUAP platform and in the Central Repository of Electronic Document Templates you can find documentation and files that we can download
— how is the process of issuing invoices in KSeF, including sending structured invoices, statuses and subject of correction
We immediately add an important point in time. From 1 September 2023 to 31 January 2026, the FA structure should have been applied (2). From 1 February 2026, only the FA (3) structure under KSeF 2.0 shall apply to all structured invoices issued. Therefore, it is worth working on the correct version of the structure, and not on the files circulating in the emails “from someone from 2023”.
If we want to embrace this process without manually keeping an eye on formats and statuses, later we will also show you how we can do it more comfortably in Altera.app. We can organize invoicing, document flow and archive, as well as have at hand the history of activities and control over what happens with invoices in the company.
National e-invoice system. How it works and what changes in document flow
At KSeF, we work differently than with classic documents sent by email. What matters here is not the appearance of the file, but whether the invoice has been correctly described with the data and uploaded to the system. In practice, this means going from “we issue PDF” to “we send invoice data in a specific structure” and the system verifies it.
If the document meets the requirements, the invoice goes to the KSeF. We get the UPO and the KSeF number, that is, the identifier assigned to the invoice in the system. If something does not match, the system rejects the document and we must correct the data and not “replace the PDF”.
This approach changes the circulation in the company, because:
— we catch formal errors more quickly even at the stage of issuing
— we work on consistent data, not on multiple versions of files circulating in emails
— we have a single point of reference for structured invoices and their statuses
When to start using KSeF and what are the basics of access
We start with access and permissions, because without this there is no secure invoicing in KSeF. In practice, we need to determine who in the organization has the right to issue, receive and view documents in the system and on what basis.
On the formal side, we act in accordance with the announcements of the Ministry of Finance and the principles of KSeF 2.0. As of February 1, 2026, there is an up-to-date approach to system versions and document structures, so we are not relying on 2023 files or descriptions for earlier versions.
The most important elements of the start:
— choosing how to authenticate and grant permissions
— setting roles, who exposes, who accepts, who only previews
— selection of a tool that generates invoice data in the required format and can send them to KSeF
What the information booklet explains and what it leaves between the lines
The information brochure organizes the basics, that is, what the National E-Invoice System is and how to understand a structured invoice. It is crucial to distinguish: an e-invoice is commonly associated with a PDF, and in KSeF it is a document based on data that must be structured according to the requirements.
What usually only follows from practice is the fact that the system looks at the consistency of the data. It is not enough to enter the TIN and the amount. What matters is the logic of the fields, the relationships between the sections, and whether the document conforms to the logical structure. If errors appear, we return to the invoice data, and not to the appearance of the document.
It is also important to remember the VAT context. In invoices sent to KSeF, we must ensure the correct marking and consistency of calculations. This also applies to special situations where additional fields or markings appear, for example for advance invoices, adjustments, RR VAT, procedures such as VAT margin, settlements within VAT groups or in the GST area.
Where to find additional information materials and how to read them
When we need certain sources, we stick to official publications. Additional information materials can be found on the gov.pl portal. In practice, we go to the appropriate tab and use documents describing requirements, deadlines and documentation.
An important distinction is this: messages and descriptions are one thing, and patterns and schemes are the other. XML document structure patterns were published in the Central Repository of Electronic Document Templates (CRWDE), which can be accessed via the ePUAP platform. Therefore, when files with the note “KSeF downloadable” circulate in the company, we always check whether it is the correct version of the structure and whether it applies to the KSeF in the version we are working on.
In practice, we read the materials like this:
— first the deadlines and requirements to know what is in effect from February 1, 2026.
— then documentation and diagrams to know what the logic of the e-invoice looks like and its logical structure
— at the end of the process of issuing invoices in KSeF, to understand the identifier, KSeF number, UPO, sending invoices to KSeF and the statuses of structured invoices
Scheme FA. What does the logical order and logical structure of the document look like
When we talk about KSeF, it is not enough to “issue an invoice”. We need to prepare the data in such a way that it matches what schema FA describes. This is a technical pattern that tells the system where the seller's data is in the document, where the buyer's data is, how we save the positions and what the summaries look like. Thanks to this, KSeF can automatically check if the document is correct.
In practice, this means one thing: a structured invoice adopts XML format and must comply with a logical structure, that is, with a data system that the system understands. When we come across a rejection, the problem rarely lies in the “content of the invoice”. Most often, the problem is that the data does not fit into the logical structure of the e-invoice or does not match the connection between the fields.
How to read mandatory and optional fields without guessing
In the scheme we always have mandatory fields and optional fields. The first ones must appear, because without them the document will not pass validation. The latter only appear if the case in question concerns our invoice.
In order not to guess, we stick to a simple rule. First, we look at the foundation, that is, the data of the entities appearing on the invoice and the data of the invoice. Only then do we add special elements.
Most often, in practice, we work around such areas:
— seller data and buyer data, including identifiers and addresses
— type of document and dates, which must be logically consistent
— invoice items, units, quantities, prices, VAT rates
— summaries that must result from the position and not be “typed by hand”
In the structure itself, we can find the separation of pages into elements of the Subject1 and Subject2 types. This helps describe the roles on the transaction side and organize the data in a way that the system clearly interprets.
What must match between sections for validation to pass
Validation in KSeF acts as a consistency check. The system checks not only whether the field exists, but also whether the data between the KSeF sections match.
The most common points that must agree:
— the sums and VAT values of the items must give the same results as the values in the summaries
— buyer and seller data must be consistent throughout the document, not just in one place
— the annotation or additional markings must correspond to the type of invoice and its particulars
— the format and logic of the dates must match the type of document, including the adjustment or advance invoice
If we use KSeF 2.0, there is one more element. We need to work on the right version of the structure, because even a small difference in the scheme can cause rejection. Therefore, we are talking about the fact that the document is supposed to comply with the current logical structure of the e-invoice, and not with a file that someone once published in 2023.
How to understand the relationships between page data and positions
In the FA scheme, the document is logical. This means that the page data and the position data are not independent. What we enter at the position level must add up to what we will show in the summaries and in the tax data.
It's good to think of it as three layers:
— a layer of transaction pages, i.e. who is who and what identifiers it has
— position layer, i.e. what we sell and how we count values
— summary layer, i.e. how the system should understand VAT and total values
This approach is also crucial for specific documents, for example when a VAT invoice appears margin, issuing VAT RR invoices or settlements within a VAT group. Then it's not about “another description”, just that the schema requires a different set of fields and a different dependency logic.
How to download an XML file and implement an e-invoice in your system
In order to function properly in KSeF, we need to have two elements. First, the current documentation and the schemes and files on the basis of which structured invoices are prepared. Secondly, a tool or integration that can prepare a structured invoice in XML format and send it to KSeF in a way that complies with the requirements.
This is an important distinction. We don't “download an invoice in XML” to manually rewrite it. We download schemes and documentation so that our invoicing generates invoice data in the correct layout and in the correct version of the logical structure of the e-invoice. In practice, we work on the schema (e.g. XSD files) and field descriptions, and only then our system generates the finished XML. Sometimes we also download sample XML files to understand more quickly how the data is arranged in a document.
Where to download the documentation and how to stick to the correct version
In practice, we rely on materials published by the Ministry of Finance. Documentation and schemes are made available in official places, and invoice structure templates were published in the Central Repository of Electronic Document Templates on the ePUAP platform, i.e. in CRWDE.
If we have files with the entries “KSeF in version” or “new scheme” in the company, we always verify that:
— this applies to KSeF 2.0
— this applies to the correct version of the structure
— this applies to the current period, i.e. changes in force after 1 February 2026.
This is especially important, because in 2023 there were publications and updates of patterns. For example, the updated FA structure template (2) was published in CRWDE on June 29, 2023, and the production environment was adapted to FA (2) from September 1, 2023. Therefore, we stick to the rule: we only work on official files and documents, and not on versions circulating in emails without a certain source.
If we use ePUAP, in practice we go through the ePUAP platform and the electronic document templates section, where the repository stores the published patterns. This source helps us confirm that we are using the correct schematics and the correct version of the structure.
Test and production environment, what does this mean in practice
In KSeF we have a separation into test and production environment. This means that:
— on the test we can check the process of sending invoices to KSeF without risk for real settlements
— on production, the issuance of invoices in the KSeF has formal effects, and the document receives the number of KSeF and UPO
From the perspective of implementing e-invoicing, the most important thing is that we do not mix these worlds. In the tests we check the validation, compliance with the logical structure of the e-invoice and the reactions of the system. In production, process safety, entitlements and clear display rules matter.
If we use ePUAP to download patterns, we still remember that the very place where the patterns are published does not mean that the file in question is “for today”. What matters is the version of the structure and whether it is a new logical structure effective after February 1, 2026 or something that should have been applied until January 31, 2026.
What to do when there are changes in the format
Changes in structures are a real scenario. Therefore, instead of treating the implementation as a one-time action, we arrange the process so that changing the version of the structure does not ruin the work.
In practice, we do three things:
— we keep up-to-date documentation and downloadable materials in one place so that the team does not work on “random XML from mail”
— we monitor which version of the logical structure of the e-invoice is generated by our tool and whether it is compatible with KSeF 2.0
— we maintain a status check mechanism to quickly see if an invoice has been accepted or rejected
If the system rejects the document, we do not try to “bypass” the validation. We return to the invoice data and to the scheme, check in which section the inconsistency appeared, correct the data and only then send the document again.
Structured invoice. How to structure data so that it passes validation
At KSeF, we do not “fill in the invoice” in the classical sense. We arrange the data in a structure that the system understands and verifies. Therefore, a structured invoice adopts XML format and must follow a logical structure. If an inconsistency appears somewhere in the data, validation will catch it and the document will not pass.
Crucially, validation doesn't just check individual fields. Checks the logical layout of the data, that is, whether the seller data, the buyer data, the positions and the summaries form a coherent whole. This is exactly the moment when “nicely typed” does not mean “properly structured”.
Data of the parties to the transaction, which must be consistent from the first field
We start with the foundation. The data of the entities appearing on the invoice must be completed consistently, because the system compares them between sections. Most often, validation catches errors when:
— the buyer's data are entered differently in different places of the document
— the seller's details are incomplete or do not match the entity identifier
— elements describing the roles of the parties are mixed up
— the annotation in the document suggests a special billing mode, but the fields that require this mode are missing
When it comes to tax matters, the VAT context is also important. If we issue documents in specific modes, such as VAT invoice margin, issuance of RR VAT invoices or settlements within a VAT group, it is not enough to add text in the description. We need to fill in the fields provided for in the scheme for a particular case.
If we operate in the public sector, there is also the subject of JST. In the structure there are elements that allow to describe the local government unit and its subordinate units. The lack of adequate coverage or inconsistency of the data can generate an error already at the validation stage.
Positions, rates and amounts where mistakes are most often made
The most rejections come from the fact that items and summaries “do not count the same”. The system assumes that:
— the values in the items must make up the values in the summaries
— VAT must result from the data and not be “entered manually” in the summary
— the fields for goods and services must be consistent with the type of item and the method of counting
The most common stumbling blocks in invoice data:
— separation between net, VAT and gross amounts in items and final totals
— erroneous rounding, which looks innocent on PDF, but causes inconsistency in KSeF
— mix of rates or inconsistent allocation of VAT to items
— lack of required fields in items when the schema requires them for a specific type of document
In practice, it is worth thinking about it like this: positions are the source of truth. Summaries are the result. If the results do not result from the position, validation will detect it.
Summaries, discounts and round-ups, how to close it correctly
Summaries are the most “absolute” part of the document, because they must agree mathematically and logically. This is where the system checks:
— whether the totals result from the position
— whether the VAT for the individual rates agrees with the calculations
— whether the final values are consistent after taking into account discounts and rounding
When discounts appear, we must consistently show them in the data. The “discount in the description” itself will not replace the figures if the scheme requires the discount to affect the item values or the calculations. The same applies to rounding. If we have a specific rounding rule in the system, we must maintain it so that the final results are consistent throughout the document.
In this section, it is also worth remembering about special documents. An advance invoice has a different data context than a final invoice. Similarly, VAT RR invoices and situations in which there is a VAT RR adjustment. These are not “other names.” These are cases where the schema requires a different set of fields and a different connection logic.
The process of issuing invoices. From data preparation to acceptance confirmation
In order for the issuance of invoices in KSeF to be predictable, we need to treat them as a process, not as a single action. First, we prepare the invoice data in the appropriate structure. Then we send the document to the KSeF. Next, we check whether the system accepted the document. If so, we save the receipt and the KSeF number. If not, we go back to the data and correct what is blocking the validation.
This approach works regardless of whether we issue the simplest document, VAT margin invoice, advance invoice, documents for JST or VAT RR invoices. The fields differ, but the logic of the process is the same.
Structured invoice shipping statuses and how to interpret them
After submitting a document to the KSeF, status information always appears. This signals whether the invoices are structured on the system side during processing or have already been verified.
In practice, we are interested in two key situations:
— the invoice was accepted, that is, the system registered it and assigned the KSeF number
— the invoice was rejected, i.e. the validation detected an error in the data or in the logical structure of the e-invoice
It is also important that rejection is not a “punishment”. This is information that the data does not fit the scheme. Then we do not do workarounds or try to send “the same thing again”. We correct the invoice data and send the document again.
What to archive after shipment to easily get back to the case
After the adoption of the document by the KSeF, we should keep three elements, because they close the process formally and operationally:
— KSeF number as a document identification number in the system
— UPO as confirmation of admission
— the version of the data that was uploaded, that is, what we actually sent as XML
This is especially important when we return to cases after time, settle VAT, clarify discrepancies or have to prove when the document entered the system. Then we don't look for emails. We reach for the identifier and confirmation.
If there are several roles in the company, it is also worth keeping order in the area of authority. Issuing and receiving documents should be separated so that there is no chaos in responsibilities.
When a correction is needed, and when is it enough to improve before shipping
If the system rejected the document, the invoice is not accepted by the KSeF. Then we do not make adjustments. It is enough to correct the data and re-send the invoice to the KSeF.
The correction occurs when the invoice has been accepted and has a KSeF number and we need to change the document data for business or tax reasons. Then corrective invoices and the rules for linking the correction to the original document come into play.
In practice, most often this applies to such cases:
— change in the value, VAT rates, items or data of the parties after the adoption of the document
— correction of buyer data or seller data, if the error did not block validation, but affected the document
— correction in specific documents, e.g. VAT RR correction or correction of advance documents
It is also important to stick to deadlines and versions of structures. If we are operating in a transition period, we need to know what should have been applied until January 31, 2026, and what is valid since February 1, 2026. This affects what version of the structure our tool uses and what the logic of the e-invoice looks like in practice.
Altera.app in your daily work. Faster, cleaner, without nerves
In theory, KSeF can be grasped manually. In practice, it quickly turns out that the biggest problem is not the display itself. The problem is maintaining order in the data, checking statuses, looking for UPO and controlling what has actually been uploaded to the system. Therefore, it is worth having one tool that guides us through the process and keeps everything in one place.
In Altera.app we can approach the topic procedurally. We issue documents in the application, and after integration with KSeF, invoices are sent to the system. We see the status, and after accepting the invoice, we get the number of KSeF and UPO. This means we don't have to keep track of XML files separately, statuses separately, and confirmations separately.
One place for documents and permissions, no running around files
In everyday work, we are most tired of being distracted. Some information is in emails, some in folders, some in the system, and some in one person's head. Altera.app helps to connect this, because we keep invoice data, document flow and access in one place for people who have to issue or just preview.
This is especially important when:
— we work in a team and we have to separate roles when performing
— we handle several areas, for example sales invoicing and special documents
— we have JST type cases and JST subordinate units, where the data of the entities must be consistently entered
History of shipments and statuses in the panel, everything at hand
The most practical difference in working with the tool is that we do not have to hunt for information. After shipping, we have in one place:
— the status of structured invoices, i.e. whether the document has been accepted or rejected
— KSeF number, that is, the identifier assigned to the document
— UPO, or confirmation of admission
Thanks to this, we do not go back to the bookmarks and do not manually check if the document has passed. We see it in the panel and we can act further.
This is also an advantage in situations that in practice occur most often:
— data corrections when validation rejects a document
— return to the case after the time when we need to recreate the course of the shipment
— checking that the issuance of invoices in KSeF goes according to plan, without arrears
Start without fuss, what to prepare to enter smoothly
So that the entrance to the KSeF does not turn into chaos, we need to sort out the basics. The point is that we do not catch mistakes only after we issue several dozen documents.
At the start it is worth having arranged:
— consistent seller data and buyer data, so as not to multiply errors in the structure
— clear division of roles, who exposes, who accepts, who only reviews
— rules for specific documents such as advance invoice, RR VAT invoices, corrections and corrective invoices
If we want to have a calm everyday life, it is crucial that the tool helps us to maintain order in data and shipments, and we can focus on correct information, VAT and real work. This is exactly what we can use Altera.app for.
summary
The KSeF scheme is not a theory for technicians. This is a specific rule of the game where a structured invoice must have the data arranged according to the FA scheme and be consistent with the logical structure of the e-invoice. In practice, we work on the invoice data, not on the appearance of the document. We prepare the XML, send it to the KSeF, and at the end we get the UPO and the KSeF number, which is the number identifying the invoice in the system.
If the document is rejected, we correct the data and send it again. If the document has been accepted and we need to change something, then corrections and the subject of corrective invoices come into play. It is also crucial to stick to the correct version of the structure, especially after the changes in effect from February 1, 2026 in KSeF 2.0, because this eliminates situations in which we work on outdated files or schemas.
If we want the issuance of invoices in KSeF to be calm and repetitive, we need order in the data and in the circulation of documents. That's why you should use Altera.app. We can organize invoices and documents in one place, speed up work with OCR, have a clear acceptance flow and archive. This makes it easier for us to keep consistent data and react faster when there is a rejection or need for correction in KSeF.
