Poland's KSeF mandate (February 2026 for large enterprises >PLN 200M revenue, April 2026 for all businesses) requires every B2B invoice to pass through the government's central platform before it becomes legally valid. This CTC (Continuous Transaction Control) model demands real-time API connectivity between your ERP and KSeF — a fundamentally different challenge from simply generating a PDF.
This guide walks through the five-layer integration architecture, common pitfalls in FA(3) schema mapping, testing strategies, and operational readiness for production.
5 Layers
Integration architecture
FA(3)
Mandatory XML schema
200+
Mapped fields
<2s
Avg. validation time
Integration Landscape
The Polish ERP market is diverse — from global platforms (SAP, Oracle, Dynamics 365) to Polish-native systems (Comarch ERP, Sage Symfonia, Insert GT) to custom-built solutions. Each segment has different KSeF integration paths:
Polish ERP Vendors
Comarch ERP · Sage Symfonia · Insert GT · Enova365
Most have released native KSeF modules. Integration is typically config-based — enable the KSeF module, configure credentials, and map any custom fields. Comarch ERP Optima had a KSeF module available since the voluntary phase in 2022.
International ERPs
SAP S/4HANA · Dynamics 365 · Oracle NetSuite
SAP released Note 3418402 (KSeF connector) in Q3 2025. Dynamics 365 requires the Polish e-Invoicing module from AppSource. Oracle customers typically need middleware. Integration timelines: 2–6 months depending on customization level.
Custom / Legacy
In-house ERP · Legacy systems · Spreadsheet-based
Requires either direct KSeF API integration (significant development effort) or a middleware platform like InvoStaq. For spreadsheet-based businesses, KSeF offers a web portal for manual single-invoice submission, but this is impractical above ~50 invoices/month.
Architecture Patterns
There are three primary architecture patterns for KSeF integration. Your choice depends on your technical capacity, invoice volume, and budget:
Pattern A: Direct API Integration
Your development team builds a custom KSeF API client directly in your ERP or a microservice. This gives maximum control but requires deep knowledge of the FA(3) schema, OAuth 2.0 token management, error handling, and retry logic. Best for: large enterprises with dedicated integration teams. Timeline: 3–6 months. Cost: High (development + maintenance).
Pattern B: ERP Vendor Module
Use your ERP vendor's pre-built KSeF module (if available). This is the fastest path for businesses using Polish ERPs like Comarch or Sage Symfonia. For international ERPs, check the vendor's marketplace — SAP, Dynamics 365, and Oracle all have partner-provided KSeF modules. Best for: businesses on vendor-supported ERPs. Timeline: 2–8 weeks. Cost: Module license fee.
Pattern C: Middleware Platform (Recommended)
A compliance middleware like InvoStaq sits between your ERP and KSeF. Your ERP exports invoice data in its native format (CSV, JSON, IDOC, etc.), the middleware handles FA(3) mapping, API authentication, submission, error handling, and status tracking. This decouples your ERP from KSeF's specifics, making upgrades easier. Best for: multi-ERP environments, international businesses with Polish operations. Timeline: 1–4 weeks. Cost: Per-invoice or SaaS fee.
FA(3) Field Mapping
The FA(3) schema is Poland's proprietary XML structure for e-invoices. It is NOT compatible with UBL 2.1 or CII — you cannot submit a Peppol BIS 3.0 invoice to KSeF. The key mapping areas:
Critical FA(3) Field Groups
Invoice type code, KSeF system date, currency code (ISO 4217), payment due date, invoice number format. The header also contains the FA version identifier — must be 'FA(3)' for current submissions.
NIP (10-digit format, no hyphens), company name, registered address (Polish voivodeship codes), VAT registration status, bank account (IBAN format mandatory for Polish accounts).
NIP (for B2B), or PESEL/passport for B2C. Address fields follow the same structure as seller. For EU buyers, use the country-specific tax ID prefix.
Line items with PKWiU codes (Polish Classification of Products and Services), unit prices, quantities, VAT rates (23%, 8%, 5%, 0%, ZW exempt, NP not applicable). Each line must calculate correctly — KSeF validates arithmetic.
Total amounts per VAT rate, grand total, payment method code, annotations (e.g., reverse charge notation, split payment annotation 'mechanizm podzielonej płatności' — mandatory for invoices >PLN 15,000).
Common Mapping Pitfalls
- • NIP format: Must be exactly 10 digits, no hyphens, no spaces, no country prefix
- • Decimal precision: Amounts must use exactly 2 decimal places (not 4)
- • Date format: YYYY-MM-DD (ISO 8601) — no time component allowed
- • VAT rate coding: Use "23" not "0.23" — KSeF expects integer percentage values
- • Split payment flag: Mandatory annotation for invoices exceeding PLN 15,000 with specified goods/services
- • GTU codes: 13 commodity group codes (GTU_01 through GTU_13) — required when applicable, omitted when not
Testing & Validation
KSeF provides a dedicated test environment (środowisko testowe) at ksef-test.mf.gov.pl. Use it extensively before going live:
Before hitting the API, validate your FA(3) XML against the XSD schema locally. This catches 80% of structural errors without consuming API rate limits. Use xmllint, Saxon, or your programming language's XML validation library. The official XSD is published by the Ministry of Finance.
Verify OAuth 2.0 token generation, API endpoint connectivity, and basic request/response handling. Submit a minimal valid invoice and confirm you receive a KSeF number back. Test both synchronous (single) and asynchronous (batch) submission modes.
Test at least these scenarios: standard invoice, credit note referencing a KSeF number, advance invoice (zaliczkowa), self-billing, split payment flagged invoice, multi-currency invoice, zero-rate export, reverse charge, invoice with GTU codes, and an intentionally invalid invoice to test error handling.
If you process >100 invoices/day, run a load test. Submit your typical daily volume in a 1-hour window. Monitor: average response time (target: <2s), error rate, rate limit hits (429 responses), and token refresh behaviour under load. KSeF's current rate limit is 500 requests/minute.
Set up a secondary test account to play the buyer role. Verify that invoices submitted by the seller appear in the buyer's retrievable list. Test date-range queries, status filters, and batch download. Confirm that your inbound processing pipeline correctly parses FA(3) XML.
Simulate KSeF unavailability. Verify that your system queues invoices for later submission, tracks pending items, and automatically resubmits when KSeF comes back online. Test the 7-day resubmission window for offline invoices.
Go-Live Operations
Once testing is complete and you're ready for production:
Production Credentials
Switch from test to production environment (ksef.mf.gov.pl). Generate production OAuth tokens using your company's real qualified electronic signature or Trusted Profile. Production tokens have different rotation policies — plan for automated refresh.
Monitoring Dashboard
Set up real-time monitoring for: submission success rate (target: >99.5%), average validation time, rejection rate by error code, queue depth (for async mode), and token expiration alerts. InvoStaq's Traffic Light Protocol provides instant visual status.
Incident Playbook
Document procedures for: KSeF outage (switch to offline mode, track pendingitems), mass rejection (halt submissions, diagnose root cause, fix mapping, resubmit), token expiration (auto-refresh with fallback manual process), and rate limit throttling (implement exponential backoff).
Continuous Optimization
After go-live, monitor rejection patterns weekly. Common first-month issues: inconsistent NIP formatting from legacy data, missing GTU codes on applicable products, and decimal rounding differences between ERP calculations and KSeF's expected precision. Refine mappings iteratively.
Cost of Integration by Pattern
| Pattern | Timeline | Dev Cost | Best For |
|---|---|---|---|
| Direct API | 3–6 months | €40K–€120K | Enterprise, custom ERP |
| Vendor Module | 2–8 weeks | €2K–€15K | Standard ERP users |
| Middleware | 1–4 weeks | €0.10–€0.50/inv | Multi-ERP, international |
Skip the Build — Use InvoStaq's KSeF Connector
Pre-built FA(3) mapping, OAuth management, async submission, error handling, and monitoring — your ERP connected to KSeF in 1–4 weeks.