/
eInvoices KSeF

eInvoices KSeF

Overview

eInvoices KSeF is a transport module for eInvoices exporter allowing you to export your HostBill invoices into KSeF API (Polish: Krajowy System eFaktur).

Module requires:

 

Activating the module

  1. If the plugin is included in your HostBill edition you can download it from your client portal.

  2. If the plugin is not included in your HostBill edition you can purchase it from our marketplace and then download it from the client area.

  3. Once you download the plugin extract it in the main HostBill directory.

  4. Go to Settings → Modules, find and activate eInvoices KSeF. 

  5. Once the plugin is activated you will be directed to Settings→ Modules→ Plugins to configure the plugin.

Module configuration

Fill in the configuration fields:

  1. Module display name

  2. NIP - Your Company NIP number, used on invoices and for KSeF connection

  3. Mode - KSeF API Mode - pick between test/demo/production. When using test mode ensure to use fake NIP number

  4. Auth Method - Select between token and certificate authentication method this module should use to connect to KSeF API

  5. KSeF Token - Enter your KSeF Token, required if Auth Method is configured to use it

  6. Certificate Path - Full path to .p12 certificate file - used for authorization (uwierzytelnianie w systemie KSeF). Required if Auth Method is configured to use it. Ensure to place it outside of the webroot. If you have certificate generated in MCU portal you can convert it to .p12 using this module, see Converting MCU Certificates below.

  7. Certificate Password - .p12 certificate password - used for authorization (uwierzytelnianie w systemie KSeF).

  8. Offline Certificate Path - Full path to .p12 certificate file - used for offline mode (Podpis linku do weryfikacji wystawcy). Ensure to place it outside of the webroot. If you have certificate generated in MCU portal you can convert it to .p12 using this module, see Converting MCU Certificates below. Required for QR codes

  9. Offline Certificate Password - .p12 certificate password - used for offline mode (Podpis linku do weryfikacji wystawcy). Required for QR codes

  10. Offline Certificate Serial Number - .p12 certificate serial number - used for offline mode (Podpis linku do weryfikacji wystawcy). Required for QR codes

  11. QR Codes Path - Full path where QR code images will be saved, should be writeable by php process. Consider to place it outside of the webroot.

  12. VAT field - Registration field responsible for storing customer vat/nip number.

  13. Additional Org number field - Optional registration field responsible for storing customer additional registration number, ie regon

  14. Company Name - Full name of your company

  15. Company Address 1 - Your company address

  16. Company Address 2 - Second line of address for your company

  17. Company Email - Your company billing email

  18. Company Phone - Phone number of your company

  19. KRS - KRS (if present)

  20. REGON - REGON (if present)

  21. BDO - BDO (if present)

  22. Bank Account Number - Your company Bank Account Number/IBAN. Optional

  23. Bank Name - Name of your bank. Optional

  24. Bank Swift code - Swift code for your bank. Optional

  25. Always include bank details - When enabled bank details will be always sent to KSeF, even if invoice is not unpaid

  26. Force 2nd Currency - When enabled your invoices a not issued in PLN, invoice will be sent to KSeF converted to PLN configured in 2nd currency option (configured in Settings -> Billing -> Document templates).
    Example: if primary invoice currency in HB is USD, and 2nd currency option is enabled (and set to PLN), invoice will be sent to KSeF as if it was issued only in PLN

  27. Use 2nd Language - When enabled and invoice lines are translated to 2nd language, invoice lines will be sent to KSeF in 2nd language

  28. Use Due Date - When enabled invoice due date will be set as FA(3): TerminPlatnosci

  29. OSS Procedure - Enable if your company is part of OSS procedure, where it can have tax rates different that the ones in Poland for B2C EU invoices

  30. Anonymize invoice - This option works only in KSeF test mode/environment.

    When enabled, invoice details like: item descriptions, notes, customer and your company details (but not NIP), will be anonymized (replaced with random characters) in FA(3). Useful for testing exporting actual invoices against test environment.

  31. Global Tax exemption - Enable if your company uses "zw" as tax, used with P_19C

  32. Global Tax exemption reason - Enter explanation (podstawa prawna) for using tax exemption P_19C

  33. Store UPO - Enable to download and store UPO xml files upon invoice delivery

  34. UPO files storage path - Full path where UPO xml files will be saved, should be writeable by php process. Consider to place it outside of the webroot.

  35. Shared items PKWiU - Enter shared PKWiU for all invoice items that cannot be determined via dedicated module settings. Leave empty if it should not be set in FA(3)

  36. Shared items GTIN - Enter shared GTIN for all invoice items that cannot be determined via module settings. Leave empty if it should not be set in FA(3)

  37. Shared items GTU - Pick shared GTU for all invoice items that cannot be determined via module settings. Leave empty if it should not be set in FA(3)

  38. Items unit - Items unit (P_8A) defaults to: szt.

  39. Invoice footer text - If this field is filled it will be always added as a footer text (Stopka faktury).


    image-20260227-150757.png

     

     

Once configuration options are set, ensure to click on Test module settings & connectivity button, to verify if the module can:

  • connect to selected KSeF API

  • read certificate files

  • write QR codes into destination directory

image-20260227-154020.png

 

Obtaining KSeF tokens/certificates from MCU

In order to connect to KSeF API you will need either a token or a certificate generated in MCU / Aplikacja Podatnika KSeF. For generating QR codes and putting them on invoices issued in HostBill you will need a certificate too.

To generate a connection token go to Tokeny → Generuj token. For exporting invoices you only need the “wystawianie faktur” scope.

image-20260227-145851.png

To generate certificate for QR codes, proceed to Certyfikaty → Wnioskuj o certyfikat. Generate new key, ensure to store/remember passphrase.

image-20260227-150116.png

Select “Podpis linku do weryfikacji wystawcy” as “Przeznaczenie certyfikatu”, generate certificate.

image-20260227-150207.png

Once the certificate gets issued, proceed to Certyfikaty → Lista certyfikatów to copy Certificate Serial Number (Numer seryjny certyfikatu) - it will be required for QR code generation.

image-20260227-150703.png

 

If you want to make use of certificate for API connection, repeat steps above for separate certificate, ensuring to select “Uwierzytelnienie” as certificate purpose

 

Converting MCU Certificates

To be able to generate QR codes and in case of using certificates for API connection, you will need to convert MCU-generated certificate (*.crt, *.key) into .p12 certificate format module “understands”. To make it easier, module adds feature for conversion under Extras → Plugins → KSeF.

image-20260227-144508.png

To create .p12 version of certificate:

  • select .crt file downloaded from MCU

  • select .key file downloaded from MCU

  • enter certificate passphrase (set when generating key in MCU)

  • hit Generate certificate → browser should send you a .p12 file.

  • Upload .p12 certificate file into path configured in module settings

GTIN/GTU/PKWiU classifications

In module configuration you can define shared GTIN/GTU/PKWiU classification for all items on exported invoices. If certain products should have its own individual classifications, you can set them in Extras → Plugins → KSeF → GTIN/GTU/PKWiU classification.

image-20260227-144838.png

When generating FA(3) file module will look for target classification for each individual invoice line

  • If none is set for related product, category one would be applied

  • If product/category cannot be applied/found shared one from module settings will be used

  • In case that no matching and shared configuration is set -> related field in FA(3) would not be set

KSeF QR codes on HostBill invoices

KSeF specification requires to place certain QR codes on invoice that is sent or shown. eInvoices KSeF module can generate them for you automatically.

When invoice is scheduled to export, but not yet exported (KSeF: offline24 mode) module will let you render 2 QR codes on invoices:

  • offline QR

  • certificate QR

When invoice gets successfully exported to KSeF, module will let you render online QR code.

 

Add following code to your HostBill Invoice template in place where you want to render QR codes:

{if $ksef} {if $ksef.status == 'offline'} {ksefqr type='offline' width="250" align="left"} {ksefqr type='cert' width="250" align="left"} {else} {ksefqr type='online' width="250" align="left"} Identyfikator faktury w KSeF: {$ksef.id} {/if} {/if}

 

Testing module

It is advised to first test the module capabilities in test API mode, before sending actual invoices into production system. To test:

  • Disable autoexport in eInvoices Exporter module

  • Select test API mode in eInvoices KSeF module

  • Generate fake PL company credentials, ie using: https://danetestowe.pl/generator/firmowe

    • store them in eInvoices KSeF module configuration

    • consider enabling Anonymize invoice option in module configuration to send anonymized invoice contents to test environment

  • Authenticate to test KSeF: Krajowy System e-Faktur using generated fake NIP number, to generate certificates and tokens

    • Convert downloaded certificates and store them in module configuration

  • Attempt to export single invoice from your system using eInvoice → Schedule button.

    • Export only invoice that you do not plan to export into production mode

  • Wait up to 5 minutes for cron to pick up invoice for delivery

  • Refresh invoice page to verify outcome.

Using eInvoices KSeF

  • eInvoices Exporter module is used to schedule invoice exports, whilst eInvoices KSeF performs actual FA(3) XML generation and delivery to KSeF API. Depending on configuration exporter module, exports can be automated (ie. as soon final invoice gets issued after payment).

  • You can track current state of delivery in adminarea invoice details, or in eInvoices Exporter module listing.

  • When DEBUG log level is enabled in General HostBill settings module will log each API request into separate log file, accessible from module page in Extras → Plugins → KSeF

  • Module will export each attempted invoices (regardless if recipient is from EU/PL/World or B2C/B2B/B2G)

  • Module currently do not export / create Faktura Korekta - this feature is being developed

  • Once invoice is exported it is not possible to re-export it. If you first exported invoice in test mode and wish to re-export it in live mode, relate related invoice row from database table: hb_einvoice_delivery

 

For testing purposes, module adds button KSeF button in admin UI: “Generuj aktualny XML”. This button generates FA(3) xml of current invoice state and downloads it as XML file, allowing you to validate its schema. It is possible to generate XML for invoice that was not sent to KSeF yet. Note that any changes in invoice details will be reflected in this XML (so once invoice changes and XML gets re-generated using this button, it will be new one)

To download exact XML of invoice that was sent, use “Pobierz wysłany XML”

To download UPO (Urzędowe Potwierdzenie Odbioru) for sent invoice, use Pobierz UPO XML option (available only if UPO was stored)

image-20260402-100033.png