Changelog

All notable changes to Fakturownia Pro for Magento 2 are documented here. The format follows Keep a Changelog. This project adheres to Semantic Versioning.

[1.1.0] — 2024-06-01

Breaking Changes

Minimum PHP version raised to 8.2

PHP 8.1 reaches end-of-life in November 2024. The module now requires PHP 8.2 or 8.3. After upgrading to 1.1.0, run php bin/magento setup:di:compile to ensure the DI configuration is compiled against the correct PHP version.

If you are still on PHP 8.1, upgrade your PHP version before installing this release. The composer constraint will block installation on 8.1 with a clear error message.

Queue table index added

A composite index on (status, created_at) has been added to the plugkit_fakturownia_queue table. This is applied automatically during bin/magento setup:upgrade. Stores with large queue tables (100k+ rows) will notice significantly faster cron processing after the index is created. The index creation is done without table locking via ADD INDEX ALGORITHM=INPLACE, LOCK=NONE on MySQL 8.0+ and MariaDB 10.6+.

Run after upgrading:

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

Added

Per-scope seller override per rule

Seller name, NIP, address, and bank account can now be overridden at the rule level, in addition to the existing store-scope override. This enables multi-brand Magento installations where different product categories (or different websites) invoice from different legal entities — all from a single Magento instance, without separate module installations.

Rule-level overrides take precedence over scope-level overrides, which take precedence over the Default scope. The resolution order is: Rule override → Website scope → Default scope.

Rule dry-run mode

A new --dry-run flag on the fakturownia:queue:process CLI command outputs which rules would fire and what documents would be generated without actually calling the Fakturownia API:

php bin/magento fakturownia:queue:process --dry-run --order-id=1001

The output shows the matched rule, the resolved document type, the buyer data block, and the line items that would be sent. Use this in production environments when testing rule changes — no invoices are created, no API calls are made.

GTU code inheritance

New compliance option: when enabled, the module checks the ordered simple product's GTU codes first, then falls back to the parent configurable product if the simple product has no GTU codes configured. Previously the module only checked the directly ordered product, which meant configurable products needed GTU codes duplicated on every child variant. This option eliminates that duplication.

Enable under Stores → Configuration → PlugKit → Fakturownia Pro → Compliance → GTU Code Inheritance.

Configurable product NIP display

The admin order view now shows the customer's NIP in the shipping and billing address blocks, alongside the standard address data. Previously the NIP was only visible in the Fakturownia Pro order panel, requiring a separate scroll. The NIP is now shown inline for faster order review.

Rule priority reordering via drag-and-drop

The Invoice Rules admin grid now supports drag-and-drop priority reordering. Previously, changing rule priority required editing individual rule records and setting numeric priority values. The drag-and-drop interface reorders rules and saves new priorities in a single operation without page reload.

fakturownia:generate CLI command

New command to generate or regenerate an invoice for a specific order without triggering the cron queue:

php bin/magento fakturownia:generate --order-id=000000123
php bin/magento fakturownia:generate --order-id=000000123 --force  # overwrite existing invoice

The --force flag generates a new invoice even if one already exists for the order. Use with caution — it will create a duplicate invoice in Fakturownia unless the existing one is first cancelled.

Queue bulk actions

The Invoice Queue admin grid now supports bulk "Re-queue" and bulk "Delete" actions. Selecting all failed jobs and re-queuing them takes one click rather than requiring individual record edits.

Fixed

• NIP field not showing on B2B checkout with custom checkout modules — Fixed compatibility with Amasty One Step Checkout and IWD Agency Checkout. The NIP field JS component now uses a compatibility adapter that hooks into the billing address form regardless of checkout layout.
• Credit note missing correction_id for pre-install orders — When a credit memo was created for an order placed before the module was installed (no fakturownia_invoice_id extension attribute), the credit note was generated without a correction_id. Fix: fallback lookup in the plugkit_fakturownia_invoices table by order increment ID.
• Partial refund creates duplicate credit notes — Race conditions in the queue deduplication check allowed duplicate credit note jobs when multiple credit memos were created in quick succession. Fixed with a database-level unique constraint on order_id + document_type + credit_memo_id.
• Flat catalog reindex clears GTU codes — GTU codes were removed from flat catalog rows during full reindex. Fixed by adding fakturownia_gtu_codes to the flat attribute source list.
• MPP threshold PLN conversion used wrong currency source — The MPP threshold check used base_grand_total (store base currency) instead of grand_total (order currency) for conversion, producing incorrect PLN equivalents for EUR-denominated orders. Fixed.
• Admin order grid invoice column sort SQL error — Sorting by invoice number caused a SQL error when the fakturownia_invoice_number join produced NULL rows. Fixed with COALESCE.

Changed

• DI compilation now validates API interface implementations — Added a Magento\Framework\Code\Validator\ConstructorArgumentTypes check during compilation. This catches missing constructor parameters in custom plugins that target PlugKit service contracts at compile time, rather than at runtime.

[1.0.0] — 2024-03-01

Initial release of Fakturownia Pro for Magento 2.

Added

• Composer package — Installable via private Composer repository at packages.plugkit.io. Package ID: plugkit/fakturownia-pro-magento2. Supports Composer 2.x.
• API integration — Full Fakturownia REST API integration with token-based authentication. Token and subdomain configured per website scope. Live connection test in Stores → Configuration.
• Per-state invoice rules — Configurable rules for all Magento order states and all custom statuses created in Stores → Order Status.
• Document types — VAT invoices, receipts, pro forma invoices, credit notes, and bills.
• Rule conditions — Filter rules by payment method, customer group, order total range, shipping country, NIP presence, and whether an invoice already exists on the order.
• Observer-based triggers — Real-time invoice generation via sales_order_state_change_after and sales_order_save_after observers. No polling.
• Async queue — All API calls dispatched via plugkit_fakturownia_queue and processed by a dedicated fakturownia_pro cron group. Order saves are never blocked by API latency.
• Retry queue — Failed API calls automatically retried with configurable max attempts and retry interval.
• Extension attributes — fakturownia_invoice_id, fakturownia_invoice_number, fakturownia_invoice_status, and fakturownia_nip on OrderInterface and OrderAddressInterface. Available via REST API and GraphQL.
• NIP field at checkout — Custom checkout field with client-side NIP checksum validation (JS mixin) and server-side validation (QuotePlugin).
• Split Payment (MPP) — Automatic annotation for invoices above PLN 15,000 gross.
• GTU codes — Custom multi-select product attribute fakturownia_gtu_codes. Included per line item in invoice payloads.
• EU OSS support — Per-country VAT breakdown annotation for OSS-registered stores.
• Reverse Charge — Automatic RC annotation and 0% VAT for VIES-verified EU B2B customers.
• Service contracts — DocumentGenerationServiceInterface and InvoiceRepositoryInterface for custom integrations. Stable across minor versions.
• Plugin architecture — SplitPaymentPlugin, ReverseChargePlugin, and QuotePlugin as afterPlugins. No class rewrites.
• Debug logging — Full API request/response logging to var/log/fakturownia_pro.log.
• Adobe Commerce Cloud compatibility — Tested on ECE Tools 2002.1.x. All file operations respect the read-only filesystem constraint.

Compatibility

| Component | Supported Versions | |---|---| | Magento Open Source | 2.4.5 – 2.4.7 | | Adobe Commerce | 2.4.5 – 2.4.7 | | PHP | 8.1 – 8.2 | | Composer | 2.x | | Cache backends | Redis, Varnish, file | | Search backends | Elasticsearch 7/8, OpenSearch 1/2 | | Flat catalog | Enabled and disabled | | Database | MySQL 8.0, MariaDB 10.6 |

Next Steps

• Installation guide
• Configuration reference
• Invoice rules