SemaShipping Packeta

VirtueMart shipment plugin for Zasilkovna / Packeta. Allows customers to select a pickup point or Z-Box directly in the cart, and enables shop owners to export shipments to Packeta (individually or in bulk) and print labels from the admin panel.

2. Installation

1. Download the installation ZIP file plg_vmshipment_semazasilkovna_X.Y.Z.zip.
2. Log in to the Joomla administration panel.
3. Navigate to System > Install > Extensions.
4. Upload the ZIP file.
5. A success message confirms the plugin has been installed.

Upgrade: Same procedure as installation. Joomla uses method="upgrade" and preserves all existing data.

The package also contains the system plugin plg_system_semazasilkovna, which is installed and enabled automatically. It provides the bulk export buttons in the VirtueMart orders list (see section 11).

4. Global Configuration

In the plugin settings (Extensions > Plugins > click the plugin name), fill in the global parameters that apply to all shipping methods based on this plugin:

Important: Without the API Key and API Password, the plugin will not function. The API Key is required for the frontend widget, and the API Password for backend shipment export and label printing.

6. Delivery Type

Each shipping method has a Delivery Type parameter (radio):

Pickup Points + Z-Boxes (pickup)

• A widget for selecting a pickup point is displayed on the frontend.
• The customer must select a point before placing the order.
• Supports both internal Zasilkovna points and external ones (Z-Boxes, Alzabox, etc.).
• See section 8 for details.

Home Delivery (hd)

• Only a radio button with the price is shown on the frontend – no widget.
• The delivery address is taken from the order (shipping address, falling back to the billing address).
• Requires the HD Carrier ID parameter – see section 7.

Delivery Type Parameters

8. Pickup Point Widget

For shipping methods with the delivery type Pickup Points + Z-Boxes, a "Choose Pickup Point" button is displayed on the frontend, opening the interactive Packeta Widget v6 map.

How It Works

1. The customer selects the Zasilkovna shipping method in the cart.
2. Clicks the "Choose Pickup Point" button.
3. A widget opens with a map and a list of points.
4. After selecting a point, its name is displayed below the button.
5. The selection is saved and survives payment method changes, cart updates, and navigation between checkout steps.

Session Persistence

The selected point is stored in the PHP session. This means:

• The selection survives payment method changes and other cart updates.
• After an AJAX page reload, the point is automatically restored.
• The session is cleared only after the order is successfully placed.

Point Filtering

• Country: The "Widget Country" parameter limits points to a specific country (e.g., cz for Czech Republic, sk for Slovakia).
• Carriers: The "Carrier Filter" parameter allows showing only specific point types (e.g., only Z-Boxes, only Alzabox). Pickup point carrier IDs come from the same feed as HD, but with pickupPoints: true – see section 7.

Validation: If the customer does not select a pickup point and attempts to complete the order, the message "Please select a Zasilkovna pickup point." is displayed.

10. Exporting Shipments to Packeta

After receiving an order with Zasilkovna shipping, you can export the shipment to the Packeta system directly from the VirtueMart admin.

Steps

1. Navigate to VirtueMart > Orders.
2. Open the order detail.
3. In the shipping section, you will see information about the selected point (or address for HD).
4. Click the "Create Packet in Packeta" button.
5. The plugin sends the data to the Packeta API and displays a confirmation with the packet ID.

What Gets Exported

• Pickup point: Point ID, recipient name, email, phone, weight, value.
• External point (Z-Box): Carrier ID + Point ID, plus recipient details.
• Home delivery: Carrier ID + full address (street, house number, city, ZIP code).
• COD: If the payment method is Cash on Delivery, the COD amount is automatically set.

Security

• Every export is protected by a CSRF token.
• The API password is never exposed on the frontend.
• All API requests and responses are logged in the #__sema_zasilkovna_log table (the API password is masked in logs).
• A shipment cannot be exported twice – if already exported, the message "Packet has already been exported." is shown.

12. Printing Labels

After a successful shipment export, you can download a PDF label:

1. In the order detail, click "Download Label (PDF)".
2. The browser downloads a PDF file with the label.

For downloading labels for multiple orders at once, see section 11.

Label Formats

The format is set in the global plugin settings:

Label Types

The plugin automatically selects the correct label type based on the delivery method:

• Internal Zasilkovna points: Standard Zasilkovna label (packetLabelPdf).
• External points (Z-Box) and HD: Courier label (packetCourierLabelPdf) – the plugin first requests a tracking number from Packeta.

14. 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.

16. 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 14.
• 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 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.