Go back to HikaInvoices

HikaInvoices documentation

Legacy documentation: HikaInvoices is discontinued. This documentation is preserved for existing installations and may not reflect current Joomla, HikaShop, PHP, tax, Peppol, or electronic-invoicing requirements.

Introduction

HikaInvoices is an add-on for HikaShop. It was designed to customise invoices and order documents sent to customers, and to assist with historical European MOSS reporting workflows.

Its main historical capabilities included:

In summary, the functionality added are:

Installation

HikaInvoices was intended to be installed after HikaShop. Installation was performed through the Joomla extension manager, using the extension installation function.

You can install HikaInvoices over a previous version.

  1. Back up the Joomla files and database before any change.
  2. Verify the compatibility of your Joomla, HikaShop, PHP, and database versions.
  3. Install or update the extension using Joomlas Extension Manager.
  4. Open the HikaInvoices configuration and review all storage and tax settings.
  5. Test invoice generation in a non-production environment before deployment.
Because the extension is discontinued, do not assume compatibility with modern Joomla, HikaShop, PHP, payment, e-invoicing, or tax-reporting systems.

Configuration

The following settings were historically available. Their naming and availability can vary depending on the installed HikaInvoices version and associated plugins.

General settings

Environment name
A unique server name used to qualify invoices in a multisite environment and to help keep invoice identifiers unique.
Unique Site ID
A website identifier, particularly relevant in JMS Multi Sites configurations.
Invoices root directory
The directory where invoice files are stored. Historical keywords included {root}, {root-1}, and {year}.
Invoice file name
A pattern used to build invoice filenames. Historical placeholders included {invoice_lbl}, {invoice_year}, {invoice_number}, {invoice_id}, and {time}.
Invoice unique number
An option intended to generate an invoice number independent from the standard HikaShop invoice number, particularly for shared multisite storage.
Extra unique status
A setting used to define additional order statuses that could generate a new document number, such as a refund document.
Invoice template
The PHP template path used to generate documents. Historical installations could override the default template with a custom file.
Email settings
Options for BCC recipients, email subject and body, and attachment of invoice PDFs. Historical placeholders included [INVOICE_FILENAME], [INVOICE_YEAR], [INVOICE_NO], and [NAME].

PDF signing

Historical versions could use X.509 PEM certificate files for PDF signing. Such certificate material must be treated as sensitive: restrict file permissions, protect private keys, and never expose them in a publicly accessible directory.

Recommended storage practice

For a legacy installation, invoice files, exports, logs, backups, and certificate material should be stored outside the public web root whenever possible. Review access controls and permissions before exposing or restoring an old installation.

We start to introduce the configuration parameters and after some check-list are provided to help you configuring your HikaInvoices to be compatible with European MOSS tax declaration..

Environment name: Enter a unique server name that is used to qualify each invoices when working in multisites. So manual import of invoices from other server will make the invoices key unique.

Unique Site ID: Default unique website identification on the server. When Jms Multisite is present, this is the slave site ID.

Invoices root directory:By default, the invoices are stored in the invoices subdirectory of this extension. When not empty, you can specify another place. The keyword {root}, {root-1} and {year} are available

Invoice file name:Specific how to create the invoice file name. When empty, the invoice file name is: {invoice_lbl}-{invoice_number}_{time}.pdf. Keywords available are: {invoice_lbl}, {invoice_year}, {invoice_number}, {invoice_id}, {time}

Invoice unique number:A flag that allow generating a unique invoice number instead of the HikaShop invoice number. This may help generating a unique invoice numbering across multiple websites when sharing the same invoice root directory. The principle is that each "invoice root directory" contain a special file for which the size give the invoice number.
So that, you can have multiple document number depending on the document type.

Extra unique status:In addition of the HikaShop order status "confirmed" and "invoice" that generate a number for the document, this field allow selecting other kind of status that need generating a new document number.
In example, select "Refunded" if you want to generate a new number for this type of document.
If you want a specific number number for each type of document and not a continuing number then store the document into a specific folder. To do that, specify in the "document template" a different "Invoice folder" path value.

Invoice template:Allow providing a specific invoice template to replace the default one located in plugins/hikashop/attachinvoice/attachinvoice/invoice.php and can be overwrite /media/com_hikashop/plugin/invoice.php. Following keywords are available: {root}, {root-1}

Generate document on history [status/type]: Allows defining the condition when a document (not necessary an invoice) must be generated.
The syntax is :

Here it is a sample

[created/*]=>order,
[confirmed/payment]=>payment,
[confirmed/modification]=>invoice ! important,
[confirmed]=>invoice
[confirmed/modification/>0]=>invoice ! important,
[confirmed/downloaded/>0]=>invoice ! important,

equivalent to

[order_status=created/*]=>order,
[order_status=confirmed/history->history_type=payment]=>payment,
[order_status=confirmed/history->history_type=modification]=>invoice ! important,

[order_status=confirmed/history->history_type=modification/order_full_price>0]=>invoice ! important,

[order_status=confirmed]=>invoice

 

where :

Remark: The order history type "downloaded" is added to allow generating the invoice only when a software is downloaded.

Invoice formats:List of fields that needs a specific number formatting. Syntax is: INV:%2.f = amout_net,total_tax, ...

eMail BCC:You can specify an e-mail address here which will be added as BCC

eMail subject:Subject of the email containing the invoice in attachement. Keywords available are: [INVOICE_FILENAME], [INVOICE_YEAR], [INVOICE_NO]

eMail body:When resending an invoice manually, this is the body of the email that contain the invoice. Keywords available are: [INVOICE_FILENAME], [INVOICE_YEAR], [INVOICE_NO], [NAME]

eMail attach invoice PDF:Attach invoice PDF to the email. Additional keywords are available in the eMail body to allow preview of download the PDF from the website. The keywords are : [URL_PREVIEW_INVOICE_HTML], [URL_DOWNLOAD_INVOICE_PDF]

Certificate file:The name of the X.509 certificate file which will be used for PDF invoice signing. The file must be in PEM format and located in the administrator/components/com_hikainvoices/assets/tcpdf/certificates directory of your site. Only required if you NEED to produce signed PDF documents.

Certificate secret key:The name of the X.509 certificate file containing the secret key for PDF signing. The file must be in PEM format and located in the administrator/components/com_hikainvoices/assets/tcpdf/certificates directory of your site.

Certificate secret key password:The password for your secret key, used in PDF signing

Extra certificates:The name of the X.509 certificate file containing additional certificates to attach to the signed PDF file, e.g. the root (public key) certificates of your Certificate Authority. The file must be in PEM format and located in the administrator/components/com_hikainvoices/assets/tcpdf/certificates directory of your site.

Your company name:Used when exporting the MOSS data

Your company country:This country is used when exporting the MOSS data

Your VAT Number:Used during the export of the MOSS data

Export MOSS directory:Location where must be stored the MOSS file exported. Keyword {root}, {root-1} and {year} are available to make reference to the website root directory or its parent root directory. By default the directory is {root}/export_moss.
{year} is the current year in format YYYY.
When the export directory does not exists, it is created with the permission 777 to allow other websites writing in this directory.

Export MOSS XML Format:The MOSS XML format depends on the country where you have to submit it.  

Taxation default internal code:Is the internal code to use when no tax is found for a product. Generally, this correspond to the international sales with tax = 0%. This may help you identifying those sales in your accountancy. This field is optional.

Taxation default taxation note:Is the internal code to use when no tax is found for a product. Generally, this correspond to the international sales with tax = 0%. In this case, when the national tax rate is NOT used, the law require to justify the reason of a non standard tax rate. This taxation note allows you adding this mention in the footer of the invoice. This field is optional but strongly recommended.

Debug mode:You have the choice among different debug modes:

Historical MOSS compatibility

HikaInvoices included functions related to the former European Mini One Stop Shop (MOSS) scheme for electronic services, including historical SAF-MOSS and Belgium Intervat MOSS XML export formats.

These features were designed around rules and technical specifications available at the time of development. They must not be considered evidence of compliance with current VAT, OSS, Peppol, e-invoicing, accounting, archiving, or reporting requirements.

Historical configuration checklist

To make the European MOSS compatibility, the HikaShop settings must have the following things checked:

HikaInvoices configuraton (recommandation)

By default, HikaInvoices contains default settings that we suggest to update when this is possible to store sensitive data outside of the internet URL.

The objective is to modify some update path to provide directories that are not public from internet. So outside of your website root directory.
The fields that you should review are:

Available keywords are

Multisite architectures

The European MOSS declaration must be unique per company.
So when you have multiple website, you need to merge the MOSS data coming from several websites into a single repository.

With HikaInvoices, there are different technology available to perform this "union" of the MOSS data coming from different websites.

Solution 1: Use JMS sharing facilities

When using "Jms Multi-Sites", it is possible to create multiple website that can share the same "Invoices" information. So that you will just have one DB where all the invoices will be stored.
The advantage of this solution is that you just have one instance of the Invoices as there is a single MySQL table sharing all the data for all the websites present on the same server.

Solution 2: Use HikaInvoice - Automatic Bills synchronization on the same server

Use the HikaInvoices - BILLS synchronization plugin that allows duplicating the invoices into another website.
This method can only be used when the different websites are located on the same server.
The disadvantage of this solution is that the Invoices data are duplicated.

Solution 3: Use HikaInvoice - Manual Export Bills / Import Bills

Use the HikaInvoices - Export Bills and Import Bills to export manually the data from one site that you will be imported manually into another website.
The disadvantage of this solution is that this operation is done manually.

System requirements

HikaInvoices is developed under Joomla 3.3

- HikaShop version 2.3.5 or higher 

Check Database

When inside the HikaInvoice configuration, the "Check Database" button is available.

It is used to verify the structure of the Database relative to the "HikaInvoices" tables.
This functionality is automatically called when using the "HikaShop" check database.

Check Environment

This is a special check of the environment to help the users in the configuration of HikaInvoices to be compliant with European MOSS declaration.

Invoice templates

Invoice templates were used to select and render different documents according to criteria such as sales zone, customer type, target extension, document type, publication state, and multisite identifier.

Common historical document types included:

Historical template keywords

Templates could refer to configuration, user, order, invoice, item, total, and note values through keywords such as: 

[CONFIG:xxxxx]
[USER:xxxxx]
[ORDER:xxxxxx]
[INV:xxxxx]
[ITEM:xxxxx]
[TOTAL:LABEL]
[TOTAL:VALUE]
[NOTE:DESCRIPTION]

Repeat blocks could historically be used for items, totals, notes, and conditions. Test any custom template carefully: the HTML support of the PDF rendering engine was limited, and invalid markup could result in blank or malformed documents.

Template security warning

Legacy documentation described a computation pattern that could evaluate expressions. Do not expose any template editor to untrusted users, and do not use or restore legacy expression-evaluation features without a complete security review.

The invoice templates allows you defining the layout of different documents.
This extension is designed to work with many extensions but here, we will describe the case of HikaShop eCommerce for Joomla.

The templates contains several parameters that are used as criteria to display a specific document.

The criteria are mainly:

 Beside those criteria, some output can be produced.

Finally, you have the look of the document.
You can either use a customize document or use the standard tool to create your own document look.
If you want to implement you own interface to generate the document, this is possible via the configuration of the "attachinvoice" plugin that is described in another section.
The parameters described here below describe the default "invoice" layout with its possible customization.

 The main keywords available in the template body are:

More keywords can be found in the "Keyword" button.
When using the "keyword" button to insert a keyword, the last keyword present between [] is inserted.
You can have multiple keywords into a list row when field in memory reflect an array or repetitive field.

It is also possible to add a "page break" and also possible to include the content of an article based on its ID.
This might be helpful in case, for example, where general conditions should be included in the invoice.

Remark: All the html tags are NOT allowed inside an article or the template.
The html tags allows are those provided by the "tcpdf.org" library used inside the HikaInvoices.
So, if you have an empty page when rendering an article or a template body, this might be due to invalid html tags present in the template.

The process of the document and keywords can be customized via triggers that can be implemented inside a plugins. The following triggers are available:

Native {invoice .... /} pattern

Article Insertion

Syntax: {INVOICE action=render_article | article_id=nnn /}

Compute expression

Syntax: {INVOICE action=compute | expression="ketwords" /}

Example: {INVOICE action=compute | expression="[ORDER:ORDER_SUBTOTAL]+[MISSING_KEYWORD1]+[Invalid]?"-1500"+[ORDER:ORDER_SUBTOTAL_NO_VAT]?"0"+[INV:SUBTOTAL]+(2*[INV:TOTAL])-10" /}

where



Import and export

Import invoices

Historical invoice import supported CSV or tab-delimited files. The import process was normally performed in three steps: upload and inspect the file, map columns to database fields, then execute the import.

In multisite scenarios, imports could be used to centralise invoice information from separate servers or websites. Always work from a database backup and validate imported records in a test copy before processing production data.

The main objective of the "import invoices" is to allow synchronizing the data coming for other servers to help doing the centralized MOSS tax reporting.
As the European MOSS tax must be done for a company whatever the website, this import feature allows importing the documents from several websites or servers.
When the websites are located on a same server, the "synchronization" plugin is preferred to this "manual" import processing.
The import allows CSV or tabulated files.
The format of the file is very basic.
Both invoice header and products are present on a single line.
When there are several product line then the invoice header is repeated.
This give something like

bill_namekey invoice_no parent_id id line_no sku qty Price
myservername|hikainvoice.com|1 15   10 1 hikainvoices_v1.0.05 1 75
myservername|hikainvoice.com|1 15   11 2 manual_prod_1 1 10

The mandatory fields are:

It is possible to import header only or product lines only.
When none of the columns corresponds to a product lines then only the header is imported.
For the import of the "product lines" only the header "bill_namekey" must be present to allow retrieving the internal "bill_id" generated after the import

Any first line of the import file that would have a column name starting with underscore (_) will be considered by default as a field to ignore.

The import processing works in 3 steps

  1. Upload the file for review
  2. Associate the columns of the uploaded file with the columns in the DB.
    This allow importing the data from other application and mapping the foreign name with the HikaInvoices field names
  3. Proceed with the execution of the file 

Because some fields can have special character, it is possible to encode the string using the base 64 function.
When a string start with "[base64]:" then it means that the following content is a base 64 string that must be decoded during the import.
This help, for example, import the "invoice_html" text field that may content new line, quotes and other characters that can make the formatting in CSV format difficult.

It provides the statistics on what is executed.
It starts by giving the general information concerning the number of records (lines) found in the file and if some lines were considered as valid or have errors.

After that, you have the number of "invoices" (header) that were identified. The invoices count correspond to the different "bill_namekey" found in the file and that at least contains another field name during the upload.

Finally, the number of "product lines" identified and processed.

Export invoices

Historical exports could produce CSV or tabular data for a selected date range and scope, such as document headers, product lines, or both. They could also assist with legacy synchronisation or accounting integration workflows.

The export of the invoices (and other documents) can be helpful to synchronize the invoice with another website or to help injecting the data into an accountancy application.

The export is available in CSV or tabulated format.
You can export the document for a specific range of date.

String format can be important when exporting the data for another machine with different string format.

Separator allows selecting how to export the file. Either in CSV with semis column or comma separator OR in a text format with tabulated separator

Invoice data scope describes if only the invoice header or only the invoice lines must be export or both (All).

Date from / to provides the range of date for the export. When used to synchronize HikaInvoices for the european MOSS tax reported, the range date will generally be a quarter.

Export MOSS

The former MOSS export targeted invoices containing a MOSS service code and could generate historical reporting formats. It is preserved only as legacy documentation and should not be used as a current compliance mechanism.

This export only concerns the electronic services. In other words, the invoices that contain a "MOSS service code".
You can select the period for which you want to extract the invoices for the export.
Normally the export should be done every quarter but we let the period open.

You can select among several format that may depends on the country where you need to declare the TAX.
Most of the countries just provide manual encoding via internet but some also provide the possibility to import a specific file.

The parameters are:

Plugins and integrations

Show Last Invoice number

When the "Unique Invoice Number generation" plugin is installed and enabled, it allows displaying the latest (current) invoice number generated.

Get New Invoice number

When the "Unique Invoice Number generation" plugin is installed and enabled, it allows create (reserve) a new invoice number that can be used for example when creating a manual invoice outside the website.

Editors-xtd : HikaInvoices keyword plugin

Extends the editor with the "Keyword" button.
The "keyword" button is only available inside HikaInvoices and in particular in side the template invoice editor where it allows retrieving the available keywords.

HikaInvoices keyword

Inside the keyword popup, you can retrieve the keyword relative to a specific invoice number and also filter them based on their names or values.
So that, it can be easy to retrieve the name of a keyword based on its value or the reverse.

HikaShop Attach Invoice plugin

This plugin historically generated and sent PDF documents when an order reached a relevant status. It included options for invoice folders, filename patterns, document templates, email copies, attachment behaviour, PDF footer content, and front-end or back-end overrides.

Attach invoice is a HikaShop plugin is use to generate and send the PDF document when a customer has confirmed and paid its order.

The parameters are:

HikaShop Invoice Integration plugin

This integration added HikaInvoices functionality within HikaShop, including historical fields for tax categories, MOSS service codes, tax notes, tax codes, and tax country identifiers.

Invoice integration plugin is the "HikaInvoices" integration inside HikaShop.
It adds the "HikaInvoices" menu inside HikaShop and also enhance HikaShop with some functionality to be complaint with European MOSS declaration.
This adds some fields inside the hikashop tables to store the additional MOSS compliant fields.
This mainly enhance the tax category, tax rate to add the MOSS Service code, tax ICC, Tax code

Unique Invoice Number plugin

The unique-number plugin was intended for multiple websites sharing a common invoice storage model. Carefully review numbering, access locking, backup, and legal record-retention implications before relying on any legacy mechanism.

When a company has several websites and wants to perform the European MOSS declaration required for the Electronic Services, it is generally recommended to have a single invoice number across all the websites.
This plugin allow generating a unique invoice number for several websites located on the same server.
By default, its parameters are collected from the HikaInvoices configuration but can be overridden inside the plugin.

The parameter is:

Bills synchronisation plugin

This plugin could duplicate invoice data into another website or central repository on the same server. It relied on trusted local configuration access and should not be enabled without a thorough security and data-integrity review.

When several websites are located on the same server, it is possible to send all the invoices( bills) into a bills "warehouse" that would centralize all the data into a single place to help in the tax reporting and tax export.
Each site that needs to send its data to another one just have to provide the path of the "configuration.php" file of the other website.
This will allow the plugin directly write a copy of each records into the other website.
If the access to the other "configuration.php" is restricted, you can make a local copy of the "configuratoin.php" or create a specific files that contain the DB connection with the same syntax as the one in the "configuration.php".

The parameters are:

Hikashop - VAT plugin

Historical plugins provided VAT verification caching, alternate verification facilities, and optional geolocation integration. External services, endpoints, and applicable rules may have changed since the extension was last maintained.

This is the plugin that adds the VAT cache and alternate VAT website checking when the European website is not available.
It is important to have a cache of the VAT verification in case of conflict with the tax administration.
It may happen (not frequent) that some VAT number are removed during a quarter.
That mean that when you will report your European Intra-Communautary sales, some VAT number might be removed and in this case, your cache will give you the prove that at the moment of the verification, you received a success from the European websites or alternate source.

The parameters are:

Hikainvoice Geo-Localisation plugins

This plugin allows using the Jms Multisite Geo-Localisation (www.jms2win.com) in addition of the services proposed by HikaShop with the Business edition.
The Geo-Localisation is available in JMS medium or full edition.

Update/About

The Update/About menu display the current HikaInvoices version, change history and also allow the registration of the extension to get a download ID required inside the Joomla Update processing.

When the user who register the extension is the one that own a confirmed order of the extension then the download ID is automatically collected.
The Update/About menu also fill the "Joomla Update Sites" information in case where the data would not be represent or removed by a Extension / Update sites => Rebuild.

This feature requires HikaInvoices version 1.0.26 or higher AND Joomla 3.7 or higher.

Legacy notice

No warranty or current compliance claim: this documentation is supplied for archival and technical-reference purposes. It does not constitute legal, tax, accounting, security, or electronic-invoicing advice.

HikaInvoices is closed and no longer receives maintenance, security fixes, compatibility updates, or paid support. Users are responsible for evaluating replacement solutions and for meeting all current obligations in the countries where they operate.

Download HikaInvoices v1.0.29 Support information