Comprehensive Polish National E-Invoicing System (KSeF) Guide in Webito
The enactment of the National E-Invoicing System (Krajowy System e-Faktur - KSeF) by the Polish Ministry of Finance (Ministerstwo Finansów) represents a mandatory structural transformation of the B2B tax landscape in Poland. Under the new fiscal framework, traditional PDF invoices and paper printouts are legally invalid for business-to-business transactions. All corporate invoices must be generated as structured XML files conforming to the official logical structure FA(2) and transmitted directly to the central government repository.
The Webito KSeF E-Invoicing plugin automates this end-to-end fiscal workflow:
- Transforms completed sales orders into compliant FA(2) structured XML
- Validates Polish 10-digit Tax Identification Numbers (NIP) via the official Modulo-11 weighted checksum
- Negotiates secure two-phase session challenges (
AuthorisationChallengeandInitToken) - Archives the official 35-character KSeF Reference Number and legally binding UPO (Urzędowe Poświadczenie Odbioru) receipt
1. Key Legal & Technical Pillars of KSeF in Poland
| Fiscal Dimension | Statutory Requirement under Polish Law | Webito Implementation |
|---|---|---|
| Document Schema | Mandatory FA (2) XML schema (1-0E) | Automated XML generator with standard root elements |
| Fiscal Identifier | 35-character KSeF Reference Number | Extracted and saved to order history (Payment.providerRef) |
| Proof of Delivery | UPO (Urzędowe Poświadczenie Odbioru) | Direct URL to download verifiable UPO receipt XML |
| Taxpayer Validation | 10-digit Polish NIP with Modulo-11 weights | Pre-flight checksum validation before gateway transmission |
| VAT Classification | 23% (standard), 8%, 5%, 0%, and exempt (zw) | Granular line-item breakdown inside P_13 and P_14 nodes |
| Consumer (B2C) Invoices | Mandatory <BrakID>1</BrakID> identification tag | Automatically applied when buyer has no verified corporate NIP |
2. Authentication & Dispatch Sequence Diagram
mermaidsequenceDiagram autonumber actor Webito as Webito Order Engine participant Plugin as KSeF Plugin participant KSeF as Ministry of Finance KSeF Gateway participant Buyer as Polish B2B Counterparty Webito->>Plugin: transmit(orderInvoiceData) Plugin->>Plugin: Validate Seller & Buyer NIPs (Modulo-11) Plugin->>Plugin: Construct FA(2) Compliant XML Payload Plugin->>KSeF: 1. Request Security Challenge (/online/Session/AuthorisationChallenge) KSeF-->>Plugin: Return Timestamped Challenge String Plugin->>KSeF: 2. Initialize Session Token (/online/Session/InitToken) KSeF-->>Plugin: Return Active SessionToken Plugin->>KSeF: 3. Submit XML Payload (/online/Invoice/Send) KSeF-->>Plugin: Issue 35-Character KSeF Reference Number Plugin->>Webito: Record Reference Number & UPO Receipt URL Buyer->>KSeF: Downloads Official Invoice from National Government Repository
3. Merchant Onboarding & Required Credentials
To obtain merchant credentials:
- Log into the official KSeF Taxpayer Portal (Aplikacja Podatnika KSeF) at
ksef.mf.gov.plusing a qualified electronic signature, Trusted Profile (Profil Zaufany), or qualified corporate seal. - In the Tokens (Tokeny) tab, generate an authorization token with permissions to issue invoices (Wystawianie faktur).
Configuration Fields in Webito Admin:
| Field Name in Webito | Config Key | Required? | Description & Context | Production Example |
|---|---|---|---|---|
| Seller NIP | sellerNip | Yes | 10-digit Polish Tax ID without hyphens or country code | 5252344078 |
| Authorization Token | authorizationToken | Yes (Secret) | Token generated in the Ministry of Finance taxpayer portal | sec_ksef_token_abc123 |
| KSeF Environment | environment | Yes | Target gateway: test (sandbox), demo (staging), or prod (live tax office) | test / prod |
| Default VAT Rate | defaultVatRate | No | Base VAT rate applied to products (typically 23%) | 23 |
| Auto-Transmit on Order Paid | autoTransmitOnOrderPaid | No | Automatically generate and transmit e-invoice upon payment confirmation | true / false |
4. Comprehensive Error Dictionary & Troubleshooting
| KSeF Status / Error | Underlying Cause | Resolution in Webito |
|---|---|---|
415 / INVALID_NIP | Seller or buyer NIP failed the Modulo-11 weighted checksum. | Verify that the 10-digit tax ID is correct and registered in REGON/CEIDG. |
400 / SCHEMA_ERROR | Mathematical discrepancy between line-item net/VAT and gross totals. | Webito calculates exact integer Grosze math to prevent rounding mismatches. |
430 / DUPLICATE_NUMBER | An invoice with this serial number has already been registered in the fiscal year. | Webito maintains an incremental, monotonic sequence per fiscal calendar year. |
SESSION_EXPIRED | The active KSeF session token timed out. | The plugin transparently renegotiates a fresh authorization challenge. |