Changelog

All notable changes to KSeF Pro for Magento 2 are documented here. The format follows Keep a Changelog.

[2.1.0] — March 2026

Added

FA(2) schema 2.0 support

Mandatory from April 2026 per Ministry of Finance decree. Schema 2.0 revises the <Podmiot1> and <Podmiot2> block structure and updates the <StawkaPodatku> enumeration. KSeF Pro 2.1.0 generates schema 2.0 exclusively — schema 1.x documents are not accepted by the MF API after April 2026.

No configuration changes are required after upgrade. The schema version is selected automatically based on the installed version of the module.

bin/magento ksefpl:queue-status

New CLI command that outputs queue counts by status and the age of the oldest pending job:

php bin/magento ksefpl:queue-status
 
# Example output:
# Status     | Count
# PENDING    | 12
# SUBMITTED  | 3
# ACCEPTED   | 1847
# FAILED     | 2
# Oldest pending: 14 minutes

Use this in monitoring scripts and dashboards to detect queue backlogs without browser access. The command exits with code 1 if the oldest pending job is more than 30 minutes old (configurable with --warning-threshold=N).

bin/magento ksefpl:retry-failed

New CLI command that batch-retries all eligible FAILED queue entries:

php bin/magento ksefpl:retry-failed
 
# Selective retry by age:
php bin/magento ksefpl:retry-failed --failed-before="2026-03-01"

The command respects the configured maximum retry limit and skips entries that have exceeded it. Equivalent to selecting all failed rows in the audit log UI and clicking "Retry selected", but usable from cron scripts or post-deployment automation.

Credit memo support

FA(2) correction invoices (<RodzajFaktury>KOR</RodzajFaktury>) are now generated automatically when a Magento credit memo is created for an order with a KSeF-ID. The <NrFaKorygowanej> element references the original KSeF-ID. Correction invoices follow the same cron session lifecycle as standard invoices.

This replaces the previous manual workflow of creating a KOR document from the audit log UI. Credit memos now trigger correction invoice generation the same way that Magento invoices trigger standard invoice generation.

KSEFPL_API_TOKEN environment variable

KSeF Pro now checks for this environment variable before reading the encrypted token from core_config_data. This enables token storage outside the database, which survives MAGE_KEY rotations and database clones on Adobe Commerce Cloud:

# In .env.php or cloud environment variables:
KSEFPL_API_TOKEN=your_ksef_token_here

Environment variable takes precedence over the database value. The connection test reads from the environment variable when present.

Verified compatibility: Magento 2.4.7-p3, PHP 8.3, Adobe Commerce Cloud 2024.Q4 toolchain.

Fixed

• setup:di:compile failure with Magento_WebapiAsync disabled — KSeF Pro's async queue processor referenced a class from the Magento_WebapiAsync module. If that module was disabled (common on Magento Open Source), DI compilation failed with a ReflectionException. Fixed by making the dependency optional via a di.xml virtual type.
• Session token transient not cleared in Redis Cluster — When the Redis cache backend was configured as a Cluster (multi-node), the ksefpl_session_token cache entry was not reliably deleted on token revocation due to how cluster key distribution works. Fixed by using Magento's CacheInterface::remove() with explicit tag flushing.
• <DataWystawienia> wrong date with differing store and server timezones — KSeF Pro was reading Invoice::getCreatedAt() and converting using the server timezone rather than the Magento store timezone (general/locale/timezone). For stores configured with Europe/Warsaw but running on UTC servers, invoices created near midnight Polish time had a one-day date offset in the FA(2) XML. Fixed: date conversion now uses the store's configured timezone.

After Upgrading to 2.1.0

Run the standard Magento upgrade sequence:

php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:clean

No database schema changes in this release. The FA(2) schema version switches automatically — no re-submission of already-accepted invoices is needed.

[2.0.0] — January 2026

Breaking Changes

Minimum PHP version raised to 8.1

PHP 8.0 reached end-of-life in November 2023. Update your PHP version before upgrading.

Module namespace changed

From Plugkit_Ksefpl to PlugKit_KsefPl. Run php bin/magento setup:upgrade before php bin/magento setup:di:compile when upgrading from 1.x. The upgrade script migrates configuration keys and queue data automatically.

If you have custom modules that depend on KSeF Pro's service contracts or observers, update their di.xml references from the old namespace to the new namespace before running setup:di:compile. The service contract interface names themselves have not changed — only the module namespace.

XML storage path changed

From var/ksefpl/ to var/ksefpl/xml/. A compatibility symlink is created automatically during setup:upgrade. Remove the symlink manually after confirming all existing XML files are accessible via the new path:

# After upgrading, verify files:
ls var/ksefpl/xml/
 
# Remove symlink when confirmed:
unlink var/ksefpl

Added

• Paired Mode with Fakturownia Pro for Magento 2 — Dual-channel invoicing from a single invoice save event. KSeF-ID passed to Fakturownia Pro via ksefpl_ksef_id_received Magento event. Both "KSeF first" and "Simultaneous" trigger modes. See Paired Mode.
• ksefpl_ksef_id_received Magento event — Dispatched when a UPO is downloaded and a KSeF-ID is assigned. Event data includes invoice_id, ksef_id, upo_path, and order_id. Any custom module can observe this event for ERP integrations, BI tools, or notification systems.
• bin/magento ksefpl:test-connection — Runs the full challenge/response authentication flow and reports success or the specific error code. Supports --scope-code flag for multi-store NIP testing.
• bin/magento ksefpl:check-tax-mapping — Lists all active Magento tax rules with their mapped Polish VAT codes. Highlights unmapped rules that will default to 23%.
• Per-website scope configuration — KSeF token, seller NIP, and all settings configurable per website scope for multi-entity Magento installations.
• Adobe Commerce Cloud environment variable support — KSEFPL_API_TOKEN and KSEFPL_SELLER_NIP environment variables take precedence over core_config_data. Survives database clones and MAGE_KEY rotations.

Fixed

• Observer fired on invoice re-save — Editing an existing Magento invoice (e.g., adding a comment) triggered sales_order_invoice_save_after and created a duplicate queue entry. Fixed by checking isObjectNew() before queuing.
• MAGE_KEY rotation detection — Previously, a rotated MAGE_KEY caused a silent AUTH_ERROR status. Now: decryption failure produces a clear error message in the connection test and a banner in the Admin configuration screen.

[1.3.1] — November 2025

Fixed

• PHP 8.3 deprecation — mb_convert_encoding() with null as the encoding argument is deprecated in PHP 8.3. Fixed in the FA(2) XML builder's string normalisation step. This fix is critical for servers upgrading to PHP 8.3 — without it, FA(2) XML generation fails for orders with special characters in address or company name fields.
• Cron lock not released on OOM kill — When the PHP process was killed due to memory exhaustion mid-session, the Magento cron lock for ksefpl_process_queue was not released. Subsequent cron runs skipped the job indefinitely. Fixed by registering a shutdown function to release the lock on process termination. If you have a stuck cron lock from a previous OOM event, manually clear it: php bin/magento cron:unlock --job-code=ksefpl_process_queue.

[1.3.0] — September 2025

Added

• bin/magento ksefpl:process-queue — Manual queue processing command. Bypasses the cron schedule and processes all pending queue entries immediately. Useful for testing and post-downtime recovery.
• Audit log UI in Magento Admin — Accessible via Sales → KSeF Pro → Audit Log. Columns: Invoice ID, Order ID, Document Type, KSeF-ID, Status, Session Ref, Submitted At, Accepted At, Error, Actions.
• Tax rate mapping UI — Visual mapping table in Stores → Configuration → PlugKit → KSeF Pro → Tax Rate Mapping. Each active Magento tax rule is listed with a dropdown for the Polish VAT code.

Fixed

• Multi-store: Default scope NIP used even when Website scope NIP was set — A Magento scope resolution bug caused the Default scope value to be read instead of the overriding Website scope value. Fixed by explicitly passing the scope context when loading ksefpl/seller/nip.

[1.2.0] — July 2025

Initial public release.

Included at Launch

• Composer distribution via packages.plugkit.io
• Magento 2.4.5–2.4.7 compatibility
• Adobe Commerce and Magento Open Source support
• KSeF session management (open, submit, close, terminate, poll, UPO download)
• FA(2) XML generation from Magento invoice and order data
• XAdES-BES digital signing using \Magento\Framework\Encryption\EncryptorInterface + PHP OpenSSL
• Observer-based hooks: sales_order_invoice_save_after
• Magento native cron integration (4 jobs in crontab.xml)
• ksefpl_queue, ksefpl_audit, ksefpl_sessions, ksefpl_invoice_registry database tables
• Audit log accessible via CLI (ksefpl:queue-status)
• UPO download and storage in var/ksefpl/upo/
• Signed FA(2) XML storage in var/ksefpl/xml/

Compatibility at 1.2.0

| Component | Supported | |---|---| | Magento Open Source | 2.4.5 – 2.4.6 | | Adobe Commerce | 2.4.5 – 2.4.6 | | PHP | 8.1 – 8.2 | | Composer | 2.x | | KSeF schema | FA(2) 1.x | | Cache backends | Redis, Varnish, file |

Next Steps

• Installation guide
• Paired mode
• Troubleshooting