Fakturownia Pro — Developer API Reference

This document is the technical reference for developers who need to understand how Fakturownia Pro integrates with PrestaShop, extend its functionality, or build custom integrations alongside it.

PrestaShop Hooks Registered

Fakturownia Pro registers the following PrestaShop hooks. Each hook is described with when it fires, what the module does in response, and any conditions that affect its behaviour.

Core Invoice Hooks

| Hook | When it fires | What the module does | |---|---|---| | actionOrderStatusPostUpdate | After an order's status is saved to the database | Evaluates the new status against Invoice Rules and executes the configured action (Create Invoice, Mark as Paid, etc.) | | actionOrderSlipAdd | After a credit slip is created (partial refund flow) | Stores the credit slip amount for use when the "Create Correction" action fires on a subsequent status change |

actionOrderStatusPostUpdate parameters available to the hook:

[
    'newOrderStatus' => OrderState,  // The new OrderState object
    'id_order'       => int,          // PrestaShop order ID
]

The module reads $params['newOrderStatus']->id to look up the matching rule in the Invoice Rules configuration.

Admin Display Hooks

| Hook | Page | What it renders | |---|---|---| | displayAdminOrderSide | Order detail page (back office) | The Fakturownia Pro side panel showing invoice number, type, status, PDF download link, and manual action buttons | | actionAdminOrdersListingFieldsModifier | Orders list page (back office) | Adds the "Invoice" column showing the Fakturownia invoice number per order row; clicking opens the invoice in Fakturownia |

displayAdminOrderSide renders when:

• An invoice record exists in ps_fakturapl_invoices for the order → shows invoice details + PDF link
• No invoice record exists → shows "No invoice" state with a "Create Invoice Now" manual trigger button

Customer-Facing Hooks

| Hook | Page | What it renders | Requires | |---|---|---|---| | displayOrderDetail | Customer account → order detail | Invoice panel with invoice number, type, date, and PDF download button | "Replace PS Invoicing" enabled in Advanced tab | | displayCustomerAccount | Customer account → My Account dashboard | "My Invoices" navigation entry linking to the invoice list | "Replace PS Invoicing" enabled |

When displayOrderDetail fires for an order with no Fakturownia invoice, the panel shows a "No invoice yet" message. It does not fall back to PrestaShop's native invoice — that fallback happens at the My Account level only.

Webhook Receiver

Fakturownia Pro registers a front-office controller as a webhook receiver endpoint:

https://yourstore.com/module/fakturapl/webhook

This endpoint is registered as a ModuleFrontController and listens for POST requests from Fakturownia's webhook system. The controller:

1. Verifies the request signature using HMAC-SHA256 with the shared webhook secret (configured in Advanced tab)
2. Parses the JSON payload
3. Updates the ps_fakturapl_invoices table with the new invoice status
4. Returns HTTP 200 on success or 400 on signature verification failure

Configuration Keys

All module settings are stored in PrestaShop's ps_configuration table with the FAKTURAPL_ prefix. Read them via Configuration::get().

Connection settings

| Key | Type | Default | Description | |---|---|---|---| | FAKTURAPL_API_TOKEN | string | — | The Fakturownia API Authorization Code | | FAKTURAPL_CUSTOM_DOMAIN | string | '' | Custom domain for white-label accounts | | FAKTURAPL_API_CONNECTED | bool | false | True after a successful Test Connection |

Invoice Rules settings

Rules are stored as a serialised array per shop ID:

$rules = Configuration::get('FAKTURAPL_INVOICE_RULES');
// Returns JSON: {"[status_id]": {"action": "create_vat", "send_email": true, "mark_paid": false}, ...}

Document settings

| Key | Type | Default | Description | |---|---|---|---| | FAKTURAPL_BUYER_NAME_FORMAT | string | fullname | fullname, company, or both | | FAKTURAPL_SHOW_NIP_FIELD | bool | false | Show NIP field at checkout | | FAKTURAPL_BILINGUAL | bool | false | Enable bilingual invoices | | FAKTURAPL_SELL_DATE_SOURCE | string | order_date | order_date or invoice_date | | FAKTURAPL_PAYMENT_TERMS | int | 0 | Days for payment deadline (0 = use Fakturownia default) | | FAKTURAPL_INTERNAL_NOTE | bool | false | Sync order note to Fakturownia internal note | | FAKTURAPL_NOTES_BEFORE | text | '' | Free text printed before invoice line items | | FAKTURAPL_NOTES_AFTER | text | '' | Free text printed after invoice line items | | FAKTURAPL_SELLER_NAME | string | '' | Seller name override | | FAKTURAPL_CONTACT_PERSON | string | '' | Seller contact person name | | FAKTURAPL_SHOW_BANK_ACCOUNT | bool | true | Show bank account on invoice | | FAKTURAPL_DEPARTMENT_ID | int | 0 | Fakturownia department ID | | FAKTURAPL_CATEGORY | string | '' | Invoice category |

Compliance settings

| Key | Type | Default | Description | |---|---|---|---| | FAKTURAPL_EU_OSS | bool | false | Enable EU OSS flagging | | FAKTURAPL_SPLIT_PAYMENT | bool | false | Enable MPP annotation | | FAKTURAPL_REVERSE_CHARGE | bool | false | Enable reverse charge | | FAKTURAPL_GTU_MAPPINGS | text | '' | JSON mapping of category ID to GTU code |

Advanced settings

| Key | Type | Default | Description | |---|---|---|---| | FAKTURAPL_OID_DEDUP | bool | false | Enable OID deduplication | | FAKTURAPL_REPLACE_PS_INVOICING | bool | false | Replace PrestaShop invoicing with Fakturownia portal | | FAKTURAPL_WEBHOOK_SYNC | bool | false | Enable webhook status sync | | FAKTURAPL_PDF_CACHE | bool | false | Enable local PDF caching | | FAKTURAPL_WEBHOOK_SECRET | string | '' | HMAC secret for webhook signature verification |

Payment mapping

$mappings = Configuration::get('FAKTURAPL_PAYMENT_MAPPINGS');
// Returns JSON: {"ps_wirepayment": "transfer", "ps_checkpayment": "cash", ...}

Database Schema

Fakturownia Pro creates one custom table: ps_fakturapl_invoices.

CREATE TABLE `ps_fakturapl_invoices` (
  `id_invoice`         INT(11) UNSIGNED NOT NULL AUTO_INCREMENT,
  `id_order`           INT(11) UNSIGNED NOT NULL,
  `id_shop`            INT(11) UNSIGNED NOT NULL DEFAULT 1,
  `fakturownia_id`     INT(11) UNSIGNED NOT NULL,
  `invoice_number`     VARCHAR(64) NOT NULL DEFAULT '',
  `invoice_type`       ENUM('vat','proforma','receipt','correction','cancel') NOT NULL DEFAULT 'vat',
  `status`             ENUM('issued','sent','paid','cancelled','overdue') NOT NULL DEFAULT 'issued',
  `pdf_url`            TEXT,
  `pdf_cached_at`      DATETIME DEFAULT NULL,
  `oid`                VARCHAR(64) DEFAULT NULL COMMENT 'Unique order identifier for deduplication',
  `date_add`           DATETIME NOT NULL,
  `date_upd`           DATETIME NOT NULL,
  PRIMARY KEY (`id_invoice`),
  UNIQUE KEY `id_order_shop` (`id_order`, `id_shop`),
  KEY `fakturownia_id` (`fakturownia_id`),
  KEY `oid` (`oid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Notes:

• The UNIQUE KEY on (id_order, id_shop) means one Fakturownia invoice record per order per shop. If OID Deduplication creates a rejected duplicate, the existing record is updated in place with the returned invoice data.
• pdf_cached_at is set when a PDF is fetched and cached. NULL means the cache is cold or disabled.
• oid is the unique order identifier sent to Fakturownia for deduplication. Format: {shop_id}-{order_id}-{timestamp_hash}.

Webhook Payload Format

When Webhook Sync is enabled and Fakturownia sends a status update, the payload format is:

{
  "event": "invoice.status_changed",
  "invoice_id": 12345,
  "external_id": "1-456-a3f9b2",
  "new_status": "paid",
  "invoice_number": "FV 2026/03/042",
  "changed_at": "2026-03-15T14:32:00+01:00"
}

Event types:

| Event | Meaning | |---|---| | invoice.status_changed | Invoice status updated (paid, sent, cancelled, overdue) | | invoice.created | New invoice created (relevant if invoices are also created manually in Fakturownia) | | invoice.updated | Invoice data changed (e.g., payment date updated) |

Signature verification:

Fakturownia signs each webhook request with HMAC-SHA256. The signature is in the X-Fakturownia-Signature header:

$secret = Configuration::get('FAKTURAPL_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
$expectedSignature = hash_hmac('sha256', $payload, $secret);
$receivedSignature = $_SERVER['HTTP_X_FAKTUROWNIA_SIGNATURE'] ?? '';
 
if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(400);
    exit('Invalid signature');
}

Extending the Module with Custom Hooks

Fakturownia Pro dispatches custom events that you can listen to from a companion module:

actionFakturaPlInvoiceCreated

Fires after a Fakturownia invoice is successfully created and saved to ps_fakturapl_invoices.

Parameters:

[
    'id_order'           => int,     // PrestaShop order ID
    'fakturownia_id'     => int,     // Invoice ID in Fakturownia
    'invoice_number'     => string,  // Full invoice number
    'invoice_type'       => string,  // 'vat', 'proforma', 'receipt', 'correction'
    'fakturownia_response' => array, // Full API response from Fakturownia
]

Use case: Trigger a custom CRM update, loyalty point award, or analytics event when an invoice is created.

// In your companion module's hook:
public function hookActionFakturaPlInvoiceCreated(array $params): void
{
    $orderId = (int) $params['id_order'];
    $invoiceNumber = $params['invoice_number'];
    
    // Example: send invoice number to your CRM
    MyCrm::recordInvoice($orderId, $invoiceNumber);
}

actionFakturaPlInvoiceFailed

Fires when an invoice creation attempt fails (API error, connection error, or validation error).

Parameters:

[
    'id_order'      => int,    // PrestaShop order ID
    'error_code'    => int,    // HTTP status code or cURL error code
    'error_message' => string, // Human-readable error message
    'action'        => string, // The action that was attempted ('create_vat', 'mark_paid', etc.)
]

Use case: Alert your ops team via Slack or email when invoice creation fails for an order.

filterFakturaPlInvoiceData

Fires immediately before the invoice creation API call. Allows modifying the invoice data that will be sent to Fakturownia.

Parameters:

[
    'invoice_data' => array,  // The full data array that will be sent to Fakturownia API
    'id_order'     => int,    // PrestaShop order ID
    'action'       => string, // 'create_vat', 'create_proforma', etc.
]

Return the modified invoice_data array from your hook method. The module uses the returned value for the API call.

Use case: Add custom fields to invoices (e.g., a project number from a custom order field), override the invoice description, or append custom line items.

public function hookFilterFakturaPlInvoiceData(array $params): array
{
    $data = $params['invoice_data'];
    $orderId = (int) $params['id_order'];
    
    // Add a custom project number from a custom order field
    $projectNumber = $this->getProjectNumberForOrder($orderId);
    if ($projectNumber) {
        $data['description'] .= "\nProject: {$projectNumber}";
    }
    
    return $data;
}

Reading Invoice Data in Custom Code

To retrieve Fakturownia invoice data for a PrestaShop order in your own module:

use PrestaShop\Module\Fakturapl\Repository\InvoiceRepository;
 
$repository = new InvoiceRepository(Db::getInstance());
$invoice = $repository->findByOrderId((int) $orderId, (int) $shopId);
 
if ($invoice !== null) {
    $invoiceNumber = $invoice['invoice_number'];
    $invoiceType   = $invoice['invoice_type'];
    $status        = $invoice['status'];
    $pdfUrl        = $invoice['pdf_url'];
}

Or query the database directly:

$invoice = Db::getInstance()->getRow(
    'SELECT * FROM `' . _DB_PREFIX_ . 'fakturapl_invoices`
     WHERE `id_order` = ' . (int) $orderId . '
     AND `id_shop` = ' . (int) $shopId
);

Next Steps

• Troubleshooting — use the error codes and log messages from this reference to diagnose issues
• Configuration Guide — all configuration keys are explained in context there
• Invoice Rules — understand when hooks fire and what data is available