Use KSeF API 2.0 with the FA(3) invoice structure, which has been mandatory since February 1, 2026. Build against the Ministry’s OpenAPI specification and official SDKs, test in the demo and test environments first, and authenticate with a method that fits your entity type. Plan for XAdES-BES signing, short-lived authentication challenges and production rate limits before go-live.
TL;DR:
- Generate your client and CI contract tests from the Ministry’s OpenAPI specification, because API 1.0 is incompatible with version 2.0.
- Match authentication to your legal form and permissions; enterprise integrations should favor KSeF certificates, implement XAdES-BES signing, and authenticate again when challenges expire.
- Validate invoices against FA(3) before submission; Offline24 invoices must reach KSeF by the next business day, while emergency mode allows seven business days after resolution.
- Use batch sessions for volume and retrieve failed invoices through the dedicated endpoint; request higher production limits early with peak load metrics.
Which KSeF API environments and documents should you start with?
The integrator support page lists three environments, and each has a distinct job:
- Production (api.ksef.mf.gov.pl): the production environment.
- Integrative (test) (api-test.ksef.mf.gov.pl): testing against the v2 OpenAPI JSON.
- Demo (api-demo.ksef.mf.gov.pl): a pre-production sandbox for rehearsing complete flows.
Use the OpenAPI JSON as the basis for your integration. Generate a client from it, then use the same file for contract tests in your CI pipeline, so a spec change fails a build instead of a production session. The test portal provides access to the test API documentation.
Watch the changelog closely. Changes to fields can affect parsing, archival and UPO handling. The Ministry’s publication of the API documentation also covers the SDKs and guidance for starting in test environments. Anything built for API 1.0 needs rework, because version 1.0 is not compatible with 2.0.
How do you authenticate with KSeF, and where do integrations break?
Authentication is the most common source of failed integrations, mainly because methods are segmented by legal form. Individuals can use Trusted Profile or a qualified signature. Entities use qualified seals, tokens in some contexts, or KSeF certificates, as the KSeF portal explains. Tokens are being phased out for general use, so for stable enterprise integrations we plan around KSeF certificates.
A practical sequence:
- Confirm which method your entity type allows and which context (NIP, PESEL or internal identifier) you act in.
- Verify that the right permissions are granted, using the MCU module for certificates and permissions, rolled out from November 1, 2025.
- Request KSeF certificates, which are available through the API and the taxpayer application and support offline issuance.
- Implement XAdES-BES signing for certificate-based authentication in commercial systems.
- Handle the challenge and response cycle with JWT access tokens, and re-authenticate gracefully when a challenge expires.
The authentication manual covers fingerprint retrieval and test-mode signing options.
Pro Tip: Check the authentication flow in the authentication manual and test your implementation in the available test environment.
What do FA(3) and the transmission modes mean for invoice dates?
Submitted XML must conform to FA(3), and per the KSeF 2.0 handbook invalid files are rejected, with a UPO assigned only after successful validation. Validate against the schema and required fields before you submit anything.
The mode you use changes the legal date logic:
- Online: follow the issuance-date rules for this mode in the invoice modes table.
- Offline24: you populate P_1 with the issuance date, and the invoice must reach KSeF by the next business day.
- Unavailability mode: consult the invoice modes table for its rules.
- Emergency mode: the deadline is 7 business days after the incident is resolved.
The invoice modes table spells out QR code and P_1 requirements when an invoice is shared outside KSeF. Attachments use the FA(3) attachment node, but according to the official Q&A some advanced features, attachments included, need commercial integrated software rather than the free Ministry tools.
What does a practical ERP integration workflow look like?
A practical integration workflow can follow this order:
- Discovery: map your internal invoice model to FA(3), identify the contexts you act in and list the permissions each needs.
- Prototyping: generate a client from the OpenAPI spec or adopt the SDK, implement the challenge and response flow, and sign test requests where needed.
- Session flows: choose interactive sessions for single invoices and batch sessions for volume. Plan UPO handling, per-invoice status checks and failed-invoice retrieval from the start.
- Testing: use the demo and integrative environments to test your integration, including batch failures and invalid XML.
- Production: request higher limits if your volume needs them, switch credentials, and enable alerts for failed sessions and certificate expirations.
Batch sessions deserve extra care. A single failed invoice can complicate UPO retrieval, so use the failed-invoices endpoint to pull only the failures instead of relying on the session-level UPO. Our post on tenant-scoped B2B SSO covers session design patterns that carry over to this authentication flow.
How should you test, and how do you raise API limits?
Use the environments for what they are. The integrative environment works with anonymized data, while demo and production behave differently regarding persistence, so do not assume test results transfer one to one.
Limits are handled per the Ministry’s notice for integrators:
- Default limits exist, and you can check the current values through the documented endpoints.
- On test environments you can change limits and restore defaults programmatically.
- In production, submit a justified request through the official contact form, with operational metrics and expected load.
- Modified limits apply to demo and production once granted.
Design for the defaults anyway. Use batch sessions where appropriate and retrieve failed invoices selectively, as the KSeF guidance recommends.
Pro Tip: Send your limit request early and attach real peak numbers, such as invoices per hour at month end, because vague requests are easy to defer.
Should you use the official SDKs or a generated client?
The Ministry publishes open-source SDKs for Java and .NET, and the integrator page also offers example clients. A client generated from OpenAPI makes more sense for other languages or when your CI pipeline regenerates code on every spec change.
Check these response fields in either approach:
- referenceNumber: ties your request to KSeF’s record.
- invoiceFileName: needed for consistent archival naming.
Check the API documentation for the response fields relevant to your integration.
When something fails, validate the schema first, then reproduce the error payload in the interactive documentation and compare it with the changelog. For documentation design, a good model is the Customerscore API reference, which shows how to structure developer onboarding.
Our perspective: where in-house KSeF work stops paying off
Most teams underestimate KSeF because the first successful test call feels like the finish line. The real work is everything after it: certificate lifecycle, XAdES-BES signing, batch failure recovery and monitoring that catches a lapsed certificate before month-end invoicing does. Our approach starts with discovery, maps legacy invoice formats to FA(3), then builds signing, batch handling and alerting as first-class parts of the system. Building in-house makes sense when invoice volume is modest and your team already owns the ERP. A partner earns its place when signing is new to you, volume is high or the invoicing stack is old. You can see comparable delivery work in our case studies.
— Vlad
How can we help with your KSeF integration?
If your ERP is complex, your volume is high or certificate handling is unfamiliar territory, we can take on the integration with you. Our team covers discovery, integration engineering, XAdES-BES signing, QA and production onboarding. For a first step, we suggest a technical audit through our technology consulting services. Contact us and we will review your invoicing landscape.
This article is general information, not a substitute for advice from a qualified financial advisor. Consult a qualified financial professional about your own circumstances before acting on anything here.
FAQ
What do I need before connecting to KSeF API 2.0?
You need FA(3)-compliant invoice output, an authentication method that fits your entity type, and access to the Ministry’s OpenAPI specification. Start in the test and demo environments before touching production, as described on the integrator support page.
Why does my KSeF authentication keep failing?
Authentication can fail if the method does not match your entity type or if required permissions are missing. Check the authentication manual and verify your setup. Check the authentication manual for guidance on authentication and test-mode differences.
How do I send many invoices without hitting rate limits?
Use batch sessions, paginate with the continuation token and retrieve only failed invoices instead of polling each one. If defaults still fall short, request higher limits through the form described in the Ministry’s notice.
Can I use the official SDKs for KSeF integration?
Yes. The Ministry maintains open-source SDKs for Java and .NET that take care of security and session handling. A client generated from OpenAPI is the alternative for other languages.
Sources
Keep the official pages open during implementation and monitor the API changelog for spec updates.
