KSeF 2.0 Integration

KSeF (Krajowy System e-Faktur) is Poland's national electronic invoicing system operated by the Ministry of Finance. FCHub Fakturownia integrates with KSeF through Fakturownia's built-in KSeF support, allowing invoices to be submitted directly from your FluentCart store.

What Is KSeF?

KSeF is Poland's centralized platform for issuing, receiving, and storing structured electronic invoices. It's part of a broader push across the EU to standardize e-invoicing and improve tax compliance.

Key points about KSeF:

• Structured format -- invoices are submitted in a standardized XML schema defined by the Ministry of Finance
• Unique KSeF ID -- every submitted invoice receives a unique identification number from the system
• Verification -- both the seller and buyer can verify invoices through the KSeF platform
• Legal compliance -- KSeF invoices are considered the official tax document

How It Works

FCHub Fakturownia does not communicate with KSeF directly. Instead, it leverages Fakturownia's own KSeF integration. When you enable KSeF auto-send in the plugin settings, the flow is:

KSeF Status Values

The plugin tracks the following KSeF statuses, as reported by Fakturownia:

The Cron Job

The plugin uses a single-event WordPress cron (wp_schedule_single_event) for KSeF status polling. Here's the technical detail:

Event Name

fchub_fakturownia_check_ksef_status

Parameters

The cron event receives two arguments:

1. $orderId -- the FluentCart order ID
2. $fakturowniaInvoiceId -- the Fakturownia invoice ID to check

Timing

• First check: 60 seconds after invoice creation
• Subsequent checks: every 120 seconds (2 minutes) while the status is processing
• Stops when: the status changes to a terminal value (ok, send_error). Both processing and server_error trigger retries.
• Retry limit: 30 attempts (~1 hour). After that, a warning is logged and polling stops.

What It Does

Each cron execution:

1. Fetches the invoice from Fakturownia's API
2. Updates _fakturownia_ksef_status on the order
3. Stores _fakturownia_ksef_id if available (the official KSeF number)
4. Stores _fakturownia_ksef_link if available (the verification URL)
5. If status is ok -- logs a success message with the KSeF number
6. If status is send_error -- logs the error messages from KSeF
7. If status is processing -- schedules another check in 2 minutes

*/2 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1

Correction Invoices and KSeF

When a refund triggers a correction invoice, the correction is also submitted to KSeF if auto-send is enabled.

Corrections use the same single-step gov_save_and_send flag as regular invoices. KSeF data from the create response (gov_status, gov_id, gov_link) is stored immediately under the _fakturownia_correction_ksef_* meta keys. A separate cron poll is also scheduled to catch async KSeF processing.

Correction positions include the required kind: 'correction' and correction_before_attributes fields per the Fakturownia API spec.

Order Metadata

The following KSeF-related metadata is stored on FluentCart orders:

Requirements for KSeF

To use KSeF auto-send through FCHub Fakturownia, you need:

Deactivation Cleanup

When the plugin is deactivated, the KSeF status check cron job is automatically cleared:

register_deactivation_hook(__FILE__, function () {
    wp_clear_scheduled_hook('fchub_fakturownia_check_ksef_status');
});

This ensures no orphaned cron events remain after deactivation. Any pending KSeF status checks will not execute.