KSeF API - How Sparados Retrieves E-Invoices and Links Them to Customer Transactions
- Artur Rucki
- 18 hours ago
- 6 min read
Updated: 28 minutes ago
The entry into force of KSeF 2.0 is a major event for the entire financial and accounting services market in Poland. The official KSeF 2.0 API documentation was published on June 30, 2025. This version introduces a new logical structure for invoices – FA(3) – which will become mandatory from February 1, 2026, replacing the currently valid logical structure FA(2).
For integrators and software providers, this means the need to adapt their systems. The test (integration) environment was launched on September 30, 2025, and the pre-production environment on October 15, 2025. These environments allow for testing of all operations in the KSeF system using test invoice data that is not legally binding. The pre-production environment further allows for testing the authentication of companies and employees using real data and certificates that will be used in the production environment.
This gave Sparados the opportunity to verify communication mechanisms with KSeF, test the retrieving and handling of invoices, and prepare for production integration-before the system becomes mandatory for all companies in Poland.
Why Did Sparados Choose to Integrate with KSeF?
For Sparados, which operates as a fintech (e.g., offering cards and handling customer transactions), integration with KSeF brings tangible benefits:
Automatic retrieving of purchase invoices assigned to card transactions, which is a significant simplification for the accounting departments of companies using the Sparados system.
Automatic linking of invoices to the corresponding transactions in the transaction history-ensuring data consistency, order, and transparency.
Streamlining the work of financial and accounting departments - invoices automatically reach the system, reducing the need for manual pairing of documents with statements.
Transparency for users: the mobile and web application shows the status "KSeF Auto Matched," merchant data, date, KSeF number - providing certainty that the document corresponds to the actual expense.
Such integration positions Sparados as a modern e-invoice integrator, increasing automation and ease of cost management - and sets a high standard in the automation of cost settlement processes.
Technical Aspects of KSeF 2.0 Integration in Sparados
🔧 KSeF API Specification and Test Environment
KSeF 2.0 API is a REST-style interface (with SOAP options for issuing and downloading invoices in XML format), with a full specification in OpenAPI 3.0 format.
The documentation contains detailed descriptions of endpoints, data schemas, parameters, example calls, and responses in languages such as C# and Java.
The integration (test) environment is available from September 30, 2025, and the pre-production environment from October 15, 2025 - enabling integrators to prepare for the production launch.
Thanks to this, Sparados could begin development work - generating queries, parsing responses, testing flows, validation, and login authentication - before KSeF 2.0 becomes mandatory.
Authentication and Authorization
To be able to view and download business customers' invoices, Sparados must possess:
A KSeF Certificate - a digital proof of the entity's identity that authorizes communication with the API. According to the documentation, an application for a certificate can only be submitted for identity data consistent with the data to be contained in the certificate, in this case, the NIP (Tax Identification Number) of Sparados.
Appropriate access rights (invoice reading) - so that the authorized entity (Sparados) can access purchase invoices issued to client companies. In the context of KSeF 2.0, permissions are granted by the entity whose data is on the invoice to the authorized entity in the context of NIP or PESEL (Personal Identification Number).
The permissions granted by the client company to the Sparados NIP authorize Sparados-using the certificate issued for its NIP-to perform operations specified in that permission on behalf of the client.
Only after these conditions are met does the KSeF API allow for the actual retrieving of invoices - including on behalf of clients, if the client has granted such rights.
Retrieving Invoices: Methods and Typical Scenarios
Sparados's integration with KSeF uses the main mechanisms provided by the API:
Retrieving a single invoice by number (KSeF Number) - via the endpoint GET /invoices/ksef/{ksefNumber}. After authentication and with an access token, a specific invoice can be directly downloaded in XML format.
Retrieving a list of invoice metadata matching specific criteria - via the endpoint POST /invoices/query/metadata. This query allows for specifying filters by which the system should return invoices - e.g., date range, invoice type, or merchant NIP. The response provides invoice metadata in JSON format containing the most important invoice data.
Invoice Export (asynchronous) - when the query concerns a large number of invoices and we need the invoices in the complete XML format, the POST /invoices/exports endpoint can be used, providing filters and encryption parameters. The system generates an archive with invoices in the background, encrypted according to the requirements, which is later available along with the export status in the operation GET /invoices/exports/{referenceNumber}.
In practice, Sparados implements this logic: it regularly (e.g., hourly or according to a schedule) sends a query for invoice metadata for client companies, retrieves new invoices, and then automatically attempts to match them to card transactions - if data consistency (e.g., counterparty, NIP, amount, date) is sufficient.
How Does Sparados Use KSeF Integration in Practice?
The workflow adopted by Sparados may look like this:
The business client - a company cooperating with Sparados - grants read permissions for invoices to the Sparados entity (via the permissions module in KSeF).
Sparados applies for its own certificate in the KSeF system-which allows for authenticated communication with the API - this is done only once, as the authorized certificate can operate in the context of various client NIPs.
The client enables the integration in the corporate panel under the KSeF tab with the option to test the connection of the Sparados service to the KSeF system - this allows the Sparados system to execute the process only for integrated clients.
At established intervals (e.g., hourly) - it subscribes or executes queries for invoice metadata for all client companies whose transactions it handles.
Upon receiving of the metadata - it selects new invoices, downloads them, and imports them into its system.
The Sparados system automatically attempts to match the retrieved invoice to a specific card transaction - if the data matches, the invoice is marked, e.g., with the status "KSeF Auto Matched." In the application interface (mobile or web), the user sees: merchant name, invoice date, KSeF number, and status.
In this way, cost and purchase documentation becomes automatic, consistent, and organized - the accounting and financial department does not have to manually download invoices, monitor if they match transactions, or sort documents.
How Can the Sparados Model Be a Blueprint for Fintechs and Other Companies Using Cards?
Integration with KSeF 2.0 gives Sparados an advantage in:
Automation - reduction of manual work, errors, and delays in settlements.
Transparency and Compliance - invoices come from the official system, they have KSeF numbers, which increases tax inspection certainty.
Customer Convenience - the client receives a set of transactions + invoices without the need to independently download documents from the KSeF system or from vendors.
Scalability - the solution is easy to extend to subsequent client companies, without the need for individual onboarding of each supplier/invoice.
For fintechs offering cards and B2B or B2C payment processing, this model can become the standard for cost management and settlement automation - increasing efficiency and competitiveness.
Challenges and Key Success Factors for Integration
Of course, for the Sparados approach to work smoothly and without problems, the following conditions are necessary:
Granting permissions by client companies - without access rights (e.g. permissions to read invoices), Sparados will not be able to retrieve invoices. This requires good communication and client understanding of the system benefits.
Possession of a valid KSeF certificate - integrators must complete the formalities. The certificate must be issued in the name of the entity performing the integration.
Correct implementation of the FA(3) specification and encryption requirements in API 2.0 - including invoice encryption (e.g., AES-256), proper query generation, handling of certificates, and asynchronous exports.
Correct mapping of invoices to transactions - the Sparados system must have logical matching rules (e.g., date, amount, merchant, NIP) for automatic linking to be meaningful and not generate errors.
Summary
Sparados's integration with KSeF 2.0 shows how a modern integrator can use a publicly available API to automate key processes - including the retrieval of purchase invoices and linking them to actual transactions. The implementation is based on the official KSeF 2.0 documentation, the use of a certificate and granted permissions, as well as REST API mechanisms for retrieving individual invoices, metadata, and exports.
Thanks to this, Sparados provides clients and accounting departments with a complete, organized, and automated data flow - minimizing manual actions and increasing the efficiency of settlements.
