PlugKit
Fakturownia Pro M2DocumentationConfiguration

Configuration

All module settings are in Stores โ†’ Configuration โ†’ Plugkit โ†’ Fakturownia Pro in the Magento admin. The configuration uses native Magento UI components and respects Magento's full store-scope hierarchy: settings can be configured globally (default scope), per website, or per store view.

Full configuration screen showing all setting groups

Accessing Configuration

Admin path: Stores โ†’ Settings โ†’ Configuration โ†’ Plugkit (left sidebar section) โ†’ Fakturownia Pro

If the Plugkit section does not appear in the left sidebar after installation, flush the config cache:

bin/magento cache:clean config

The section appears immediately after the cache is cleared.

Store Scope Architecture

Magento's configuration scopes apply fully to all Fakturownia Pro settings:

| Scope level | Use case | |---|---| | Default (global) | Single-store Magento installations; base settings for multi-store | | Website | Different legal entities with different Fakturownia accounts or API tokens | | Store view | Different document languages (Polish PDF for PL store view, English for EN store view) |

Select the target scope from the Store View dropdown before changing settings. Settings that differ from the inherited value show the "Use Default" checkbox unchecked.

Common multi-store pattern: Global API token pointing to one Fakturownia account, with store-view overrides for Invoice Language (Polish for PL, English for EN).

General Settings Group

General settings with API token, subdomain, and test connection

| Field | Scope | Description | |---|---|---| | Enabled | Website | Enable or disable the module for this website without affecting others | | API Token | Website | Fakturownia REST API authorization code (full string including /subdomain) | | Subdomain | Website | Your Fakturownia account subdomain only (e.g., mycompany) | | Test Connection | โ€” | Fires a live GET /api/invoices.json?per_page=1 โ€” success shows account name | | Department | Website | Default Fakturownia department for generated documents | | Invoice Language | Store view | Language of generated PDFs: pl (Polish) or en (English) |

Test Connection Details

The Test Connection button makes a minimal API call to confirm credentials and connectivity. What it checks:

  1. The API token format is syntactically valid
  2. The Fakturownia API endpoint is reachable
  3. The credentials are accepted (HTTP 200 with account data)
  4. The account name returned matches what you expect

If the test fails with a timeout error, see Troubleshooting โ†’ Connection Timeout. If it fails with "Unauthorized," the API token needs to be regenerated in Fakturownia.

Document Settings Group

Document settings with seller override and buyer data source options

Seller Information

| Field | Description | |---|---| | Use account default | Use seller details configured in your Fakturownia account | | Override seller name | Company name override for this website/store | | Override NIP | Tax ID override | | Override address | Address block override | | Override bank account | Bank account override | | Override contact person | Contact name override |

Overrides are sent as seller_name, seller_tax_no, etc. in the Fakturownia API payload. They do not modify your Fakturownia account settings โ€” they apply only to invoices generated by this Magento instance.

Multi-brand use case: Two Magento websites (brand-a.com and brand-b.com) connected to the same Fakturownia account. Website A overrides the seller name to "Brand A Sp. z o.o." and website B to "Brand B Sp. z o.o." Both show the same NIP (same legal entity) but different trading names.

Buyer Data Source

The module resolves buyer data for invoice generation using this priority order:

  1. Order extension attribute fakturownia_nip โ€” set when the NIP checkout field captured a NIP
  2. Customer address attribute tax_id โ€” the standard Magento B2B VAT field
  3. Order billing address โ€” company, then firstname/lastname for the buyer name block

Invoice Number Series

Leave blank to use Fakturownia's default sequential numbering. Enter a series name to use a specific Fakturownia series. The series must exist in your Fakturownia account under Settings โ†’ Numbering before specifying it here.

Asynchronous PDF Attachment

When enabled, PDF attachment to Magento transactional emails is handled via the cron queue rather than synchronously during the order save operation. This prevents email send delays when the Fakturownia API is slow.

Trade-off: Asynchronous mode means the email is queued for sending โ€” it goes out within the next cron cycle (typically within 1 minute) rather than immediately. For most stores, this delay is acceptable.

Advanced Settings Group

Advanced settings with retry queue and logging controls

| Field | Default | Description | |---|---|---| | API Timeout | 15s | HTTP client timeout for Fakturownia API calls | | Max retries | 3 | Maximum retry attempts per failed job | | Retry interval | 300s (5 min) | Seconds between retry attempts | | Notify on failure | Admin email | Recipient for permanent failure notifications | | Debug logging | Off | Writes full API request/response to var/log/fakturownia_pro.log | | Log retention | 30 days | Auto-rotate logs older than this |

Adjusting the Cron Group Schedule

The fakturownia_pro cron group schedule can be adjusted via Stores โ†’ Configuration โ†’ Advanced โ†’ System โ†’ Cron (Scheduled Tasks):

| Job | Configurable field | Default | |---|---|---| | fakturownia_process_queue | Schedule expression | * * * * * (every minute) | | fakturownia_retry_failed | Schedule expression | */5 * * * * (every 5 min) | | fakturownia_cleanup_logs | Schedule expression | 0 2 * * * (daily 02:00) |

For very high-volume stores (10,000+ orders/day), consider changing fakturownia_process_queue to */1 * * * * (explicitly every minute) and increasing the batch size via Stores โ†’ Configuration โ†’ Advanced โ†’ System โ†’ Fakturownia Pro Queue Batch Size (default: 50 jobs per cron run).

Extension Attributes

The module registers extension attributes on Magento's core order entities. These attributes persist alongside order data and are available in Magento's REST API, GraphQL API, and admin panel.

| Entity | Attribute | Type | Description | |---|---|---|---| | OrderInterface | fakturownia_invoice_id | string | Fakturownia internal invoice ID | | OrderInterface | fakturownia_invoice_number | string | Human-readable invoice number (e.g., FS/2025/001) | | OrderInterface | fakturownia_invoice_status | string | pending, generated, failed, skipped | | OrderInterface | fakturownia_nip | string | Customer NIP captured at checkout | | OrderAddressInterface | fakturownia_nip | string | NIP on the billing address entity |

Using Extension Attributes in Custom Code

// Read invoice number from order
$order = $this->orderRepository->get($orderId);
$invoiceNumber = $order->getExtensionAttributes()->getFakturowniaInvoiceNumber();
 
// Read NIP from billing address
$billingAddress = $order->getBillingAddress();
$nip = $billingAddress->getExtensionAttributes()->getFakturowniaNip();

Orders Grid and REST API

Extension attributes are searchable via Magento's standard search API:

# Find all orders where invoice generation failed
curl -s "https://yourstoreDOTcom/rest/V1/orders?searchCriteria[filterGroups][0][filters][0][field]=fakturownia_invoice_status&searchCriteria[filterGroups][0][filters][0][value]=failed" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Admin Panel Integration

Orders Grid Column

The module adds an Invoice column to the Magento admin orders grid. The column shows:

  • Invoice number as a link to Fakturownia (for generated invoices)
  • "Pending" badge (for orders in the queue)
  • "Failed" badge with retry link (for permanent failures)
  • "Skipped" label (for orders excluded by rule conditions)

Orders grid with invoice column visible

Order Detail Panel

Each order detail page has a Fakturownia Pro panel showing:

  • Invoice number and document type
  • Generation timestamp
  • Current status
  • Links: view in Fakturownia, download PDF
  • Buttons: manual generate/regenerate

Order detail page with Fakturownia panel

Admin Menu

After installation, Plugkit โ†’ Fakturownia Pro appears in the Magento admin left sidebar, providing access to:

  • Invoice Queue โ€” view all pending, processing, failed, and completed jobs
  • Invoice Log โ€” audit trail of all generated documents
  • Settings โ€” shortcut to Stores โ†’ Configuration

Logging

Debug logging is written to var/log/fakturownia_pro.log. The log includes:

  • API endpoint called
  • Full request payload (JSON)
  • HTTP response status
  • Response body (truncated on success, full on error)
  • Order ID and the job ID in the queue table
  • Execution duration in milliseconds

Warning: Debug logs contain complete invoice payloads including buyer names, NIP numbers, product details, and pricing. Enable only during active troubleshooting and rotate immediately after.

To tail the log in real time:

tail -f /var/www/magento/var/log/fakturownia_pro.log

Next Steps

Edit this page on GitHub
Was this page helpful?

Related Documentation

This topic is also available for other platforms:

Fakturownia ProFakturownia Pro WCFakturownia Pro

Documentation

InstallationConfigurationInvoice RulesComplianceTroubleshootingChangelogArchitecture GuideCron-Based Retry QueueDocument Settings