SemaShipping Packeta

1. Requirements

• Joomla 4.x or 5.x (VirtueMart does not support Joomla 6 yet)
• VirtueMart 4.x
• PHP 8.0 or newer
• MySQL 5.7+ / MariaDB 10.3+
• Active Zasilkovna / Packeta account with API access

Checkout: The plugin works both in the standard VirtueMart checkout and in RuposTel One Page Checkout (com_onepage) – since version 1.4.0, with no extra configuration. See One Page Checkout in section 8.

Packeta Credentials You Will Need

3. Enabling the Plugin

After installation, the shipment plugin must be manually enabled:

1. Navigate to Extensions > Plugins (or System > Manage > Plugins).
2. Search for semazasilkovna or Zasilkovna.
3. Click the plugin SemaShipping Packeta - Zasilkovna shipping for VirtueMart (group vmshipment) and set Status = Enabled.
4. Save.

The system plugin plg_system_semazasilkovna enables itself during installation – no manual step required.

The plugin does not display anything on its own – you must create a shipping method in VirtueMart first (see section 5).

5. Creating a Shipping Method

The plugin serves as a foundation for VirtueMart shipping methods. A single plugin installation can power any number of methods – e.g., one for pickup points and one home delivery method per destination country.

Steps

1. In VirtueMart admin, navigate to Shop > Shipment Methods.
2. Click New.
3. Fill in:
   • Shipment Name: Name displayed to the customer (e.g., "Zasilkovna – Pickup Point")
   • Published: Yes
   • Shipment Description: Optional description
   • Shipment Method: Select SemaShipping Packeta - Zasilkovna shipping for VirtueMart

On some installations VirtueMart shows the raw language key PLG_VMSHIPMENT_SEMAZASILKOVNA in this dropdown instead of the name. This is a VirtueMart quirk (it does not load plugin language files into this list) – pick that entry, it is the right plugin. In Extensions > Plugins the name is displayed correctly.

1. Switch to the Configuration tab (per-method settings).
2. Configure the parameters described in the following sections.
3. Save.

7. Home Delivery (HD)

Home delivery works without the widget – the shipment goes to the delivery address from the order. However, each shipping method carries one HD Carrier ID, valid for one country and one carrier.

Rule: one country = one shipping method. To deliver to five countries, create five methods, each with its own Carrier ID and its own country restriction.

Steps for One Country

1. Create a new shipping method as described in section 5.
2. Delivery Type = Home Delivery (hd).
3. HD Carrier ID = the carrier ID for that country (see the table below).
4. Countries = only the single country this method delivers to.
5. Set the price, tax, and optionally the weight range (see section 9).
6. Save.

Recommended Carrier IDs for Common Countries

Alternative carriers, if their terms suit you better:

All carriers listed above have a 30 kg per-shipment limit.

Watch the "Separate house number" column: carriers marked "yes" (separateHouseNumber) require the house number in a dedicated field. See House Number below.

Verifying Carrier IDs and Finding Others

The carrier list changes over time – verify the IDs in your own account before going live. Download the home delivery carrier feed from:

https://www.zasilkovna.cz/api/v4/<API_PASSWORD>/branch.json?address-delivery

Replace <API_PASSWORD> with your secret API password (the same one configured in the plugin – not the 16-character widget API key).

The response is JSON containing a carriers object. The relevant fields for each carrier:

The same feed is available in the Packeta Client Section under Carrier Feed.

House Number

Some foreign carriers (separateHouseNumber: true) require the house number separated from the street. The plugin reads it from an order user field named house_number, which VirtueMart does not provide by default.

If you use a carrier with this requirement:

1. Navigate to VirtueMart > Shop > User Fields.
2. Create a new field with the Name set to exactly house_number.
3. Mark it as required and show it in both shipping and billing addresses.
4. Save.

Without this field, Packeta returns a PacketAttributesFault error on export.

Currency and COD

Each HD carrier accepts COD in one fixed currency (the Currency column in the tables above). If the order is issued in a different currency, Packeta rejects the COD amount.

• Either configure the matching currency for that country in VirtueMart,
• or do not offer COD on that shipping method.

See also section 15.

9. Shipping Price

Each shipping method has its own pricing settings:

The Price Is Entered WITHOUT VAT

The Shipping Cost field takes the amount before tax. VirtueMart adds VAT according to the selected Tax Rule. If you enter the amount the customer is supposed to pay, you will charge them that amount plus VAT.

Conversion table for a 21 % rate:

In general: price excl. VAT = price incl. VAT / 1.21.

Set the price when you create the shipping method. The first save sticks, but later changes to Shipping Cost on an existing method may not take effect (VirtueMart treats this field as currency-convertible and may keep the stored value on save). If you need to change the price and the change does not apply, delete the shipping method and create it again with the correct price.

Method Display Restrictions

Countries and Blocked Countries live on the first tab of the shipping method ("Shipment Method Information"), not in the Configuration tab among the other plugin parameters. VirtueMart's core fields are used – the restriction works the same, it is just configured elsewhere. If you cannot find these fields in the plugin configuration, that is why.

11. Bulk Export and Labels

To process multiple orders at once, use the buttons in the VirtueMart orders list. They are provided by the system plugin plg_system_semazasilkovna, installed automatically alongside the shipment plugin.

Steps

1. Navigate to VirtueMart > Orders.
2. In the toolbar (next to "Update Orders") you will see the "Packeta" button; it opens a menu with Export to Zasilkovna, Download Labels (PDF), Check packet statuses and Help.
3. Clicking it sends all not-yet-exported orders in the statuses configured in Export Order Status to Packeta. Multiple statuses may be separated by commas (e.g. E,Q) – see section 4.
4. Results appear in a bar below the toolbar – a packet ID for each successful order, or an error message.
5. "Download Labels (PDF)" downloads labels for every packet that exists in Packeta and is not cancelled – whatever the order status. It first asks which slot on the sheet to start from, so a partially used sheet can be finished.

Good to Know

• Already-exported orders are skipped – re-running the export creates no duplicates. If there is nothing to export, the message "No unexported orders" is shown.
• An error on one order does not stop the others. Handle failed orders individually from the order detail.
• Bulk labels cover pickup points and home delivery alike. Packeta uses a separate method for each kind, though, and will not merge them into one PDF, so a batch holding both produces two files: the first downloads straight away, the second through a button that appears in the results bar. The chosen sheet position applies to the first file; the second starts on a fresh sheet.
• The number of positions on a sheet follows the label format in the configuration: A6 on A4 has 4, A7 on A4 has 8, while A6 on A6 and A7 on A7 hold one each (there the position is not asked for and the download starts right away).
• If Order Status After Export is filled in, every successfully exported order is switched to that status – see section 10.
• If no orders show up for export, check Export Order Status first. The default C matches no orders in most shops.
• The bulk export page has a status drop-down at the top. When the configuration lists several statuses separated by commas, the whole combination is offered as the first entry (e.g. "In Process + Pending") and comes pre-selected. Picking a single status below it narrows the filter to that one; select the first entry again to return to the combination.
• Both export and label download are restricted to users with admin access and protected by a CSRF token.

13. Packet IDs and Statuses in the Orders List

From version 1.6.0 the plugin prints the packet ID under the order number in the VirtueMart orders list, and the packet status underneath it. You no longer have to open an order detail just to find out whether a packet exists and where it is.

The packet ID badge

• It appears on every order that has a packet created in Packeta – whatever the order status.
• A cancelled packet has its ID struck through, with an explanation in the tooltip.
• The badge loads together with the orders list and needs no configuration.

Check packet statuses

The status is not fetched on every page view – that would mean one Packeta request per packet and the page would open slowly. You ask for it by hand:

1. Navigate to VirtueMart > Orders.
2. In the menu under the "Packeta" button choose "Check packet statuses".
3. The plugin asks Packeta for the status of created, non-cancelled packets and stores it with the order.

Good to Know

• Packeta has no bulk equivalent of the status query, so it is one request per packet. The plugin therefore handles at most 40 packets per click and reports "N packets left – click Check packet statuses again." Click as many times as needed.
• Packets whose status was checked longest ago go first, so repeated clicking works through the whole list.
• Statuses are translated into Czech, Slovak, English, German and Polish. A status the plugin does not know is printed exactly as Packeta returned it – it is never left blank.
• A "cancelled" status is only ever added, never cleared. In the first minutes after a cancellation Packeta replicas answer inconsistently, so the flag would otherwise remove itself.
• When there is nothing to check, the plugin reports "Nothing to check – no created packet that is not cancelled."
• The status listing is available only to users with administration access and is protected by a CSRF token, just like export and labels.

15. Currencies and Rounding

The plugin sends the order currency (the currency field) to Packeta along with the shipment value and any COD amount.

• CZK and HUF have no minor unit – Packeta rejects decimal places for them and returns a PacketAttributesFault error. The plugin therefore rounds both the value and the COD amount to whole numbers for these currencies.
• EUR, PLN, and others are sent with decimal places unchanged.
• The order currency should match the carrier currency (the Currency column in the tables in section 7), otherwise Packeta rejects the COD amount.

17. Troubleshooting

Widget Does Not Appear

1. Verify the plugin is enabled.
2. Verify the shipping method has delivery type Pickup Points + Z-Boxes (not HD).
3. Check that the API Key (Widget) is filled in the global plugin settings.
4. Check the browser console (F12) for JavaScript errors.
5. Verify the page is not blocked by a Content Security Policy (CSP) for the widget.packeta.com domain.

Customer Cannot Complete the Order

• For "Pickup Points" methods, the customer MUST select a point. The message "Please select a Zasilkovna pickup point." is displayed correctly.
• For "Home Delivery" methods, no point validation is performed – if the customer cannot complete the order, the issue is elsewhere.

Error During Shipment Export

• Verify the API Password is filled in the global plugin settings.
• Verify the Sender Label matches the sender name in the Packeta Client Section exactly.
• Check the error message – the plugin displays the exact Packeta API response.
• Check the log in the #__sema_zasilkovna_log table for request and response details.

PacketAttributesFault Error

Most common causes:

• Missing house number for a carrier with separateHouseNumber: true – see House Number.
• Decimal places in CZK or HUF – handled by the rounding described in section 15.
• Sender Label mismatch with the Packeta Client Section.
• Missing phone or email for a carrier with requiresPhone / requiresEmail.
• Carrier weight limit exceeded (maxWeight, typically 30 kg).

Home Delivery Method Uses the Wrong Carrier

• Verify the HD Carrier ID matches the country set in the Countries parameter.
• Verify the carrier has apiAllowed: true in the feed – e.g., "Packeta vecerni doruceni Bratislava HD" (ID 132) cannot be used via the API.
• Verify Delivery Type is set to hd (not pickup).

Label Does Not Download

1. Verify the shipment was successfully exported (a packet ID must exist).
2. Check that the label format in the plugin settings is valid.
3. For external points and HD: the plugin needs to obtain a tracking number from Packeta. If this fails, check the API log.
4. For bulk download: external points and HD are not part of the bulk PDF – download them individually.

Bulk Export Reports "Unexpected response" or a 500 Error

This is fixed in version 1.4.3. The cause was a shipment plugin loading conflict (Joomla imports the whole vmshipment group and VirtueMart's core weight_countries plugin crashes if it loads before ours – error Class "vmPSPlugin" not found).

1. Update the plugin to 1.4.3 or newer.
2. Verify the system plugin plg_system_semazasilkovna is enabled – it is what applies the fix.
3. The symptom depends on plugin ordering, so it can appear on a site where everything worked before.

Bulk Export Finds No Orders

• Check the Export Order Status parameter. The default C (Confirmed / paid) is empty in most shops – cash-on-delivery orders never reach it.
• Find the right code in VirtueMart > Orders > Order Statuses.
• Separate multiple statuses with commas (E,Q). An empty or malformed value deliberately exports nothing.

Status check reports that the table has no status columns

The message "The shipment method table has no columns for the packet status" means the site was updated to 1.6.0 but VirtueMart has not added the new columns yet. Open and save any Packeta shipping method – VirtueMart adds them on save. It is the same situation as with cancellation, see section 2.

Cancelling a Shipment Fails With a Missing Column Error

Updating the plugin does not create new fields in the shipment table. Open any shipping method in VirtueMart and save it – this makes VirtueMart reconcile the table schema. See section 2.

A Shipment Cannot Be Cancelled (CancelNotAllowedFault)

Packeta refuses cancellation once the shipment has been handed over to the carrier. In that case resolve the situation directly in the Packeta Client Section.

Order Status Does Not Change After Export

1. Verify the Order Status After Export parameter is filled in (empty = the status is deliberately left alone).
2. Verify the code matches an existing status in VirtueMart > Orders > Order Statuses.
3. An order already in the target status is skipped.
4. If the customer receives no e-mail about the change, that is a VirtueMart setting (Configuration > Orders), not the plugin.

The Widget Opens Twice in One Page Checkout, or the Point Disappears

• Update the plugin to 1.4.0 or newer – earlier versions did not support One Page Checkout.
• Verify the OPC system plugins are enabled (plg_system_opc in particular).
• Clear both the Joomla and OPC caches.

Bulk Export Buttons Do Not Appear

1. Verify the system plugin plg_system_semazasilkovna is installed and enabled (Extensions > Plugins, group system).
2. Verify you are on the VirtueMart > Orders page (the buttons appear nowhere else).
3. Check the browser console for JavaScript errors.

COD Amount Not Set

• Verify the COD payment method ID is correctly entered in the "COD Payment IDs" parameter.
• The ID must be a number matching virtuemart_paymentmethod_id in the payment method URL.
• Separate multiple IDs with commas without spaces (e.g., 3,7).
• Verify the carrier supports COD at all (disallowsCod: false).

Shipping Method Not Displayed

• Check country settings (allowed / blocked).
• Check weight restrictions (min / max weight).
• Verify the method is Published in VirtueMart.
• Verify the plugin is Enabled.