Integrating an ERP system with KSeF step by step

ERP integration with Poland's National e-Invoicing System, KSeF (Krajowy System e-Faktur), should link the document in the ERP system to its processing outcome, KSeF number and official receipt, UPO (Urzędowe Poświadczenie Odbioru). A separate process must retrieve purchase invoices and route them for approval or posting to the accounts.

Before choosing a solution, check the exact ERP version, extensions and invoice types. A vendor connector, middleware and a custom API connection can work together within a single architecture.

Submission starts processing. Only the final outcome allows an invoice to be marked as accepted. If a response is lost, first reconcile the outcome of the previous operation instead of submitting the document again.

Accept the implementation on the basis of error-handling, recovery and purchase-invoice completeness tests. Offline procedures have different deadlines; a local Internet connection problem is not an officially announced KSeF outage.

1. Scope and responsibilities

2. Connector, middleware or a custom API integration

3. Access and environments

4. Data mapping

5. Sales, statuses and UPO

6. Purchase invoice retrieval

7. Errors and retries

8. Offline modes and outages

9. 12 acceptance tests

10. Going live and maintenance

11. Costs and requests for proposals

12. What KSeFGPT supports

13. Frequently asked questions

Start with a list of companies, taxpayer contexts and the systems in which invoices originate. Separate domestic business-to-business sales, consumer sales, international transactions, advance payment invoices, corrective invoices and self-billing. Include cases handled by ERP extensions, rather than just the standard sales form.

The KSeF obligation depends on the taxpayer and the document. VAT exemption does not automatically exclude a taxpayer, while submitting consumer invoices to KSeF is optional. Agree on the rules with accounting; a Polish tax identification number (NIP) or the invoice currency alone does not determine whether a transaction falls within scope.

Accounting approves the tax rules and invoice data. The ERP administrator confirms the data sources and the compatibility of the version and extensions. The integrator is responsible for transport, statuses and recovery. Also designate someone to respond to a queue backlog and a team to approve purchases.

The deliverable is a signed-off matrix covering document type, data source, issuance method, recipient, owner and acceptance criterion. Submitting sales invoices and retrieving purchase invoices have separate requirements. Do not postpone retrieval until submission goes live.

Ask the supplier to confirm compatibility with the specific ERP product family and version, updates, modules and custom modifications. A general statement that KSeF is supported does not establish which corrective invoices are covered, whether purchase invoices can be retrieved or how the KSeF number is stored against the document.

A connector is a ready-made connection module, usually maintained by the vendor or a partner. Middleware is an intermediary layer between systems that can manage queues and mapping. A custom integration requires a team to maintain the entire API communication lifecycle. Middleware can use a connector, so these options are not necessarily mutually exclusive.

The deliverable is a data-flow diagram and an agreement defining responsibilities. For every handoff, specify where data is persistently stored, who fixes errors and how the data returns to the ERP system. Before purchasing, request a demonstration using a set of your own anonymized scenarios.

Authentication confirms identity. Permissions determine which operations are available in a given context. Test issuance and read access separately, including after a permission is revoked. Successful login alone is not sufficient to sign off this stage.

A type 1 KSeF certificate is used for authentication. Type 2 confirms the issuer in the applicable offline procedures. A certificate does not grant permissions. A KSeF token is a different credential from the short-lived access token obtained during API communication.

Poland's Ministry of Finance (MF) states that KSeF tokens will continue to be supported indefinitely. When choosing an access method, check the current implementing regulations and API documentation. For the method you use, appoint an owner responsible for renewing, revoking and securely storing credentials. Secrets and full invoice data should not appear in ordinary diagnostic logs.

TEST, DEMO and PROD must have separate configurations, queues, archives and synchronization checkpoints. Use anonymized data in TEST. DEMO uses real authentication credentials and permissions, but its invoices have no legal effect. PROD is for genuine documents, not fictitious test invoices.

The deliverable is verified access in every required context, together with a test of losing and restoring access. Before going live, compare the actual production API contract with the contract used in testing. Planned deployment dates in the changelog do not replace this check.

FA(3) has been the structure for standard structured invoices since February 1, 2026. KSeF receives XML, rather than a PDF or spreadsheet. Prepare a separate data map and example for every supported invoice type; successfully mapping an ordinary sales invoice does not demonstrate support for advance payment or corrective invoices.

For each mapping, record the ERP source field, the structure element, the transformation rule, the condition for populating the field and the approver. Include the parties' details, dates, invoice number, currency, line items, rates, amounts, payments and links to earlier invoices. Define what to do when data is missing.

XSD validation checks compliance with the schema. Check business and tax rules separately: consistent totals, rounding, transaction classification and the correctness of a correction. Distinguish between fields required by the schema, alternative variants and fields required only in a specific case.

The deliverable is an approved mapping and a set of test documents covering every declared scenario. For each rejected document, the user should be shown the reason and where to make the correction. The guide to XML and FA(3) explains the basics of the format.

The sales workflow includes preparing and validating XML, opening a session and encrypting the data, submitting invoices, checking the outcome for each invoice and storing its KSeF number and UPO. Acceptance of a request for processing does not mean that the invoice has been accepted. In a session containing multiple documents, some may be accepted and others rejected.

Retain the exact XML that was submitted, together with its hash. A persistent operation register should link the ERP invoice to the submission attempt, references and outcome. The issuer's invoice number, technical references and KSeF number are different identifiers.

Keep the following states separate: prepared, submitted and processing, outcome unknown, rejected, accepted, and UPO archived. An accepted invoice with a missing UPO requires retrieval of the receipt, not resubmission. UPO confirms receipt by KSeF; it does not confirm acceptance of the delivery, posting to the accounts or payment.

The deliverable is the ability to trace the history of a single invoice without searching through unrelated logs. After acceptance, changing the data requires the appropriate corrective-invoice workflow rather than overwriting the accepted XML.

Purchase invoices are retrieved from KSeF for the appropriate entity context and roles. The buyer does not resubmit a purchase invoice received from the system as its own sales invoice. After retrieval, retain the XML and metadata, identify the counterparty and any links between corrective invoices and original documents, then route the document to the appropriate ERP workflow.

For receipt through KSeF, the receipt date is generally the day on which the KSeF number is assigned, not the date of a later import. Emergency modes and delivery to specified recipients outside the system follow separate rules. Retrieving an invoice does not mean that the cost has been approved or that VAT may be deducted.

Incremental retrieval requires a safe completeness boundary. MF documentation describes the permanent storage date, PermanentStorage, and the HWM marker defining the range of available documents. Do not replace it with the time on a local clock or the invoice issue date.

Handle every page, export part and truncated range. Documents at range boundaries may appear again, so deduplicate by KSeF number within the correct environment and context. Advance the synchronization checkpoint only after the entire processed range has been persistently stored.

The deliverable is a reconciled set of purchase invoices that remains complete after delayed storage, repeated retrieval and an import failure. A single invoice visible under several roles should not create several payment liabilities.

For example, the ERP system requested submission and KSeF started processing, but the connection dropped before the response arrived. Record the outcome as unknown. If you have an invoice reference, read its status; if you have only a session reference, reconcile the documents in that session. Do not create modified XML solely to retry transport.

Run retries from the persistent register, with a single active worker for each document. Duplicate status code 440 is an invoice-processing status, not an HTTP status code. Use the returned link to the original document. Local checks are still needed: the same invoice from a business perspective may contain different technical data.

For HTTP 429, respect the waiting time specified by Retry-After and throttle the relevant request group. An XML error requires data correction. Missing permissions require administrator intervention. Transient read errors can be retried with increasing intervals; every attempt should retain references and progress.

The deliverable is a controlled intervention queue and reconciliation between the ERP system, the register and KSeF. A process restart should resume submission, polling or retrieval according to the stored state. Restoring an older database backup requires reconciling documents accepted after that backup was created.

The procedure depends on the cause and the official announcement. Offline24 may also be used at the taxpayer's discretion or when there is an Internet connection problem. A local ERP failure does not automatically entitle you to the deadline that applies to an officially announced KSeF outage.

The deadlines below reflect MF information checked on October 15, 2026. Offline24 does not mean 24 clock hours. The queue must calculate working days, track announcements and raise alerts before deadlines expire. If another outage is announced in the meantime, apply the relevant rules for switching between modes.

In offline24, during unavailability and in emergency mode, the issue date is the date entered in field P_1. The receipt date depends on the mode and the recipient category. For domestic receipt through KSeF under offline24 and during unavailability, it is generally the date the KSeF number is assigned; in emergency mode, it is generally the earlier of actual receipt and assignment of the number.

When delivering an invoice before its subsequent submission to KSeF to recipients specified in Article 106gb(4) of the Polish VAT Act, the appropriate OFFLINE and CERTYFIKAT markings are required, using a type 2 certificate. For a domestic buyer with a NIP, MF describes a transaction confirmation that is not an invoice. After acceptance, an invoice visualization delivered outside KSeF carries a QR code with the KSeF number. A complete outage requires neither a KSeF QR code nor subsequent submission of the invoice.

The deliverable is an employee procedure explaining how to choose the mode, what to provide to the recipient, when to submit the document and who monitors the deadline. Merely storing XML in a queue does not complete this stage.

For every test, record the input, expected outcome, evidence of execution and the person responsible for acceptance. Use anonymized examples representing all declared invoice types. The following criteria are recommendations for implementation acceptance, not an official certificate of compliance.

First, sign off the tests in non-production environments. In production, run a limited pilot using genuine, correctly prepared documents and agree on who checks the outcome. Do not test a return to the old system by reissuing documents already accepted in KSeF.

Monitoring should show the age of the oldest invoice in the queue, unknown outcomes, rejections, accepted invoices without UPO, delays in purchase invoice retrieval, truncated exports and access errors. Assign a recipient and a response time to every alert. Set thresholds according to the company's volume and deadlines.

Maintenance covers ERP and API updates, key rotation, credential renewal, backups and recovery tests. A mapping change should trigger tests for every affected invoice type. Periodically reconcile document counts and identifiers between the ERP system, the integration archive and KSeF.

The deliverable is an acceptance report, an incident procedure and a designated maintenance owner. The supplier should also specify how XML, UPO, operation history and configuration will be handed over when the engagement ends.

Compare proposals for the same scope. Costs depend on the number of companies and systems, availability of a ready-made connector, ERP modifications, invoice types, data quality, volume, purchase invoice retrieval and the required level of maintenance. The license price alone does not automatically include analysis, testing or incident handling.

In your request for proposals, specify the ERP version, extensions, process list, volume and peak periods. Ask for separate quotes for implementation, licensing, infrastructure, maintenance and changes. Attach the mapping matrix and acceptance criteria so that you can compare genuinely equivalent proposals.

Agree on who corrects source data, monitors offline deadlines and reconciles unknown outcomes. Ask about updates following API changes, response times, the scope of responsibility and access to data after changing suppliers. Without these agreements, the cheapest proposal may cover only XML transport.

KSeFGPT provides a ready-made connection to Fakturownia.pl: configuration using a subdomain and API token, previews, individual or bulk submission, and outcome checks. Selected invoices from KSeF can also be exported to Fakturownia. The Integrations module describes the scope.

File import is a different route from a direct ERP connection. PDF files require OCR extraction and data verification, while CSV, XLS or XLSX files require parsing and column mapping. The prepared FA(3) XML is submitted to KSeF. Whether a particular ERP system can export the data must be confirmed in its configuration.

KSeFGPT does not currently have a direct SAP integration. Automatic retrieval from SAP and writing the KSeF number back to SAP remain planned features with no announced release date. Do not assume that the scope of the ready-made Fakturownia connection applies to any ERP system. Invoicing and data-exchange tools do not replace a full accounting system or a tax assessment.

Answers to questions about scope, confirmations and implementation acceptance.