Troubleshooting Fakturownia Pro

This guide covers every common issue reported by store owners using Fakturownia Pro, structured by symptom. Work through each section methodically — most problems have a clear root cause and a straightforward fix.

If you reach the end of this guide without a resolution, contact support at hi@plugkit.io. The information to include is listed at the bottom of this page.

Section 1: Connection Issues

"API connection failed" or red error badge on the Connection tab

This is the most common issue after installation. Work through these causes in order:

Cause 1: Wrong token type

Fakturownia shows multiple token types on its Integration page. You need the API Authorization Code specifically. It is a long alphanumeric string ending with /yoursubdomain, for example: AwIsZLvfOVXEGz4cNnLa/mystore.

Do not use:

• The OAuth 2.0 client secret (shorter, different format)
• The Bearer token
• The webhook secret key

Fix: Re-open Fakturownia → Settings → Account → Integration → find the "API Authorization Code" row → copy that value.

Cause 2: Extra whitespace in the pasted token

When copying a token, some browsers or text editors include trailing newlines or spaces. These are invisible but break authentication.

Fix: Copy the token, paste it into a plain-text editor (Notepad on Windows, TextEdit in plain-text mode on Mac), confirm there are no spaces before or after the string, then copy again and paste into the module.

Cause 3: Server cannot reach fakturownia.pl outbound

Some shared hosting providers block outbound HTTPS connections from PHP scripts as a security measure.

Fix: Ask your hosting provider: "Can PHP on my account make outbound cURL requests to external HTTPS URLs, specifically fakturownia.pl on port 443?" Most reputable hosts allow this; if yours does not, you will need to request an exception or switch hosts.

You can also test from your server using SSH: curl -I https://app.fakturownia.pl/ — if it returns HTTP headers, the connection is working.

Cause 4: Temporary Fakturownia API outage

Occasionally the Fakturownia API is briefly unreachable.

Fix: Open fakturownia.pl in a browser. If the site loads normally but the API is still failing from your store, check the Fakturownia status page if available, or wait 10–15 minutes and click Test Connection again.

Cause 5: White-label or custom domain account

If your Fakturownia account is accessed at a custom domain (e.g., invoices.yourcompany.pl or a custom InvoiceOcean subdomain), the module cannot auto-detect the domain from the token.

Fix: Enter the full domain in the Custom Domain field on the Connection tab. Enter only the domain without https://, for example: invoices.yourcompany.pl.

cURL Error Codes Reference

| cURL error code | Error message | Meaning and fix | |---|---|---| | 6 | Could not resolve host: app.fakturownia.pl | DNS resolution failed. Your server cannot resolve the domain. Ask your host to check DNS configuration. | | 7 | Failed to connect to app.fakturownia.pl port 443 | Port 443 is blocked outbound. Ask your host to whitelist fakturownia.pl. | | 28 | Operation timed out after 30000 milliseconds | Connection established but API did not respond. Retry — likely a temporary Fakturownia slowdown. | | 35 | SSL connect error | SSL/TLS handshake failed. Your server's CA bundle may be outdated. Ask your host to update OpenSSL. | | 60 | SSL certificate problem: unable to get local issuer certificate | PHP cannot verify Fakturownia's SSL certificate. Ask your host to update the CA certificate bundle. |

Section 2: Invoices Not Being Created

No invoice panel appears after an order status change

Work through this checklist in order:

Step 1: Confirm there is a rule for this status

Go to Fakturownia Pro → Invoice Rules tab. Find the row for the exact status name that changed. If the row exists but is set to "No Action", the module intentionally ignores it.

Important: Custom order statuses you created in PrestaShop must appear in the Invoice Rules tab. If you recently added a new custom status and do not see it listed, try resaving the Invoice Rules tab — it reloads the status list from PrestaShop on save.

Step 2: Verify the API connection is working

Go to the Connection tab and click "Test Connection". If it fails, no rule can fire — fix the connection first.

Step 3: Check the PrestaShop error log

Go to Advanced Parameters → Logs. Set the severity filter to "Error" and look for entries with "Fakturownia Pro:" in the message, timestamped around when the status change occurred.

The log entry includes:

• The order ID
• The exact error message from the Fakturownia API
• The HTTP status code (e.g., 401, 404, 422)

This is the fastest way to diagnose why a rule fired but the invoice was not created.

Step 4: Check for conflicting modules

If you previously used the official free Fakturownia module (available in PrestaShop Addons) or another third-party Fakturownia integration, it registers for the same hooks. Two modules responding to the same order status change will conflict.

Fix: Disable and uninstall any other Fakturownia integration module. Fakturownia Pro is a complete replacement, not an add-on.

Step 5: Confirm the hook is registered

In rare cases after an unusual installation, hooks may not be registered. To re-register all hooks:

1. Go to Modules → Module Manager
2. Find Fakturownia Pro
3. Click the dropdown arrow next to "Configure" → select "Reset"
4. Confirm the reset — your configuration is preserved, only hooks are re-registered

API Response Codes Reference

| HTTP code | Fakturownia API meaning | What to do | |---|---|---| | 200 | Success | Invoice created or updated successfully | | 201 | Created | Invoice created successfully | | 400 | Bad request — malformed data | Check the log for the specific field that failed validation (e.g., invalid NIP format, missing required field) | | 401 | Unauthorized | API token is invalid, wrong type, or expired — re-enter it in the Connection tab | | 404 | Not found | Trying to mark as paid or cancel an invoice that does not exist in Fakturownia | | 409 | Conflict | OID Deduplication: invoice already exists for this order ID (this is expected and correct behaviour — no duplicate was created) | | 422 | Unprocessable entity | Data was received but failed business rule validation — check the log for details | | 429 | Too many requests | API rate limit exceeded — slow down automated status changes or contact Fakturownia support to raise your limit | | 500 | Fakturownia server error | Temporary issue on Fakturownia's side — retry in a few minutes |

Section 3: Invoice Contains Wrong Data

Wrong buyer name on the invoice

Cause A: "Buyer Name Format" setting is wrong for your store type. Check Document Settings tab:

• B2B store: set to "Company name"
• B2C store: set to "Full name"
• Mixed store: set to "Company + full name"

Cause B: The order's billing address is wrong. Open the order in PrestaShop Admin → Addresses section → check the billing address. If the address data is wrong (customer entered incorrect info), edit it directly and manually trigger a new invoice via the Fakturownia Pro order panel.

Cause C: NIP field not enabled or customer did not fill it in. If the NIP is missing from the invoice, the customer did not enter it at checkout. Enable "Show NIP field at checkout" in Document Settings and add clear guidance on your checkout page encouraging B2B customers to fill in their NIP.

Wrong VAT rate on the invoice

Cause A: EU OSS is not enabled but cross-border EU sales are occurring. Enable EU OSS in the Compliance tab if you sell B2C to EU countries.

Cause B: Reverse Charge is not enabled but EU B2B sales are occurring. Enable Reverse Charge in the Compliance tab if you sell to VAT-registered EU companies.

Cause C: The product's tax rule in PrestaShop is incorrectly configured. The VAT rate on invoices comes from PrestaShop's product tax configuration — check the product's tax rule under Catalog → Products → product → Tax rule.

Wrong payment method on the invoice

The payment type on invoices comes from the Payment Mapping tab. Open it and check whether the payment module that was used for the order is correctly mapped to the right Fakturownia payment type. If the mapping is set to the default (transfer) but the customer paid by card, update the mapping for that payment module.

Section 4: Duplicate Invoices

The same order has two or more invoices in Fakturownia

Cause: A payment gateway sent its webhook callback multiple times (common with Przelewy24, PayU, and Stripe in high-traffic or network-timeout scenarios). Each callback triggered a status change, and each status change fired the Create VAT Invoice rule.

Immediate fix: Cancel the duplicate invoices in Fakturownia manually. Keep the first one (lowest invoice ID). If the duplicates were sent to the customer by email, contact the customer to explain and confirm which invoice is the valid one.

Permanent fix: Enable OID Deduplication in the Advanced tab. This sends a unique order identifier with every invoice creation request. Fakturownia rejects any subsequent requests with the same order ID with a 409 Conflict response, returning the existing invoice instead.

Database cleanup: If you need to update which invoice PrestaShop's records point to, connect to your database and update the ps_fakturapl_invoices table:

UPDATE `ps_fakturapl_invoices`
SET `fakturownia_id` = [correct_invoice_id],
    `invoice_number` = '[correct_invoice_number]'
WHERE `id_order` = [order_id];

Section 5: Customer Portal Issues

"My Invoices" section does not appear in customer accounts

Cause: "Replace PS Invoicing" is not enabled.

Fix: Go to Fakturownia Pro → Advanced tab → enable "Replace PS Invoicing" → save.

Customer sees "No invoices" even though invoices exist in Fakturownia

Cause A: The ps_fakturapl_invoices database table has no record for that order. This can happen if:

• The invoice was created manually in Fakturownia (not via the module)
• A write error occurred when the invoice was created (check Advanced Parameters → Logs for write errors around the invoice creation time)

Fix for Cause A: From the order detail page in PrestaShop Admin, use the Fakturownia Pro panel's "Link existing invoice" option (if available) or manually add a record to ps_fakturapl_invoices.

Cause B: The orders were placed before the module was installed. Historical orders do not retroactively appear in the portal.

Fix for Cause B: Use the manual invoice creation button on the order detail page in PrestaShop Admin to create invoices for historical orders on demand.

NIP field not appearing at checkout

Cause: "Show NIP field at checkout" is not enabled in the Document Settings tab.

Fix: Go to Fakturownia Pro → Document Settings tab → enable "Show NIP field at checkout" → save → clear PrestaShop cache (Advanced Parameters → Performance → Clear cache).

If the field still does not appear after cache clearing, check whether your checkout theme overrides the standard address form template. Some custom themes use heavily modified address.tpl files that do not include hook calls for custom address fields. Consult your theme developer.

Section 6: PHP, Compatibility, and Performance Issues

PHP errors after updating PHP version or PrestaShop

Fakturownia Pro is tested on PHP 8.1 through 8.4 and PrestaShop 8.0 through 9.0.3.

Fix:

1. Confirm you are running the latest version of Fakturownia Pro (check Module Manager for the version number)
2. If not on the latest version, download it from plugkit.io and upload to upgrade
3. Clear PrestaShop cache: Advanced Parameters → Performance → Clear cache
4. Check Advanced Parameters → Logs for PHP error details

Module causes significant slowdown on orders with many line items

The Fakturownia API call happens synchronously during the order status change request. On stores with very large orders (50+ line items), the API call may add 500–1500ms to the request.

Fix:

• Enable PDF Cache (Advanced tab) — reduces PDF download overhead for customers
• Contact hi@plugkit.io to request information about async invoice processing (available as a configuration option)

Slow PDF downloads for customers

Cause: PDF is fetched from Fakturownia API on every download without caching.

Fix: Enable PDF Cache in the Advanced tab. Subsequent downloads serve the locally cached PDF in milliseconds instead of making an API call each time.

Section 7: Checking Logs

All Fakturownia Pro errors are written to PrestaShop's native log system.

To view logs:

1. Go to Advanced Parameters → Logs
2. Set the severity filter to "Error"
3. Look for entries from "Fakturownia Pro" in the object type column
4. The "Message" column shows the exact error; the "Object ID" column shows the PrestaShop order ID

Common log messages and meanings

| Log message | Meaning | Fix | |---|---|---| | API request failed: 401 Unauthorized | API token is invalid or wrong type | Re-enter the API Authorization Code in the Connection tab | | API request failed: 404 Not Found | Invoice not found in Fakturownia (e.g., Mark as Paid before invoice exists) | Check rule sequence | | API request failed: 409 Conflict | OID deduplication blocked a duplicate | Expected — no action needed | | API request failed: 429 Too Many Requests | Rate limit hit | Reduce frequency of automated status changes; contact Fakturownia | | Invoice already exists for order #X | Deduplication working correctly | No action needed | | cURL error 6: Could not resolve host | DNS failure — server cannot reach fakturownia.pl | Contact your host | | cURL error 28: Operation timed out | Fakturownia did not respond within 30s | Retry — likely transient | | Order address NIP is not valid | NIP format validation failed (must be 10 digits) | Customer entered a malformed NIP — edit the order address and retry | | PDF download failed: invoice PDF not yet generated | Invoice exists but PDF not ready yet | Wait 30 seconds and retry — PDF generation is asynchronous in Fakturownia |

Still Need Help?

Contact hi@plugkit.io with:

1. Your PrestaShop version (found in Advanced Parameters → Information)
2. Your PHP version
3. The exact error message or screenshot of the problem
4. The relevant log entry from Advanced Parameters → Logs (include the full message and order ID)
5. Your Fakturownia subdomain (e.g., yourstore.fakturownia.pl) — never send your API token
6. The steps to reproduce — what status change triggers the problem, what you expected, what happened instead

We respond within 24 business hours (Monday–Friday, CET).

Next Steps

• Configuration Guide — review all settings to rule out misconfiguration
• Invoice Rules — check your rule logic for edge cases
• API Reference — technical details for developers extending the module