SemaShipping PPL

1. Requirements

• Joomla 4.x or 5.x (VirtueMart does not support Joomla 6 yet)
• VirtueMart 4.x
• PHP 8.0 or newer, with the cURL extension
• MySQL 5.7+ / MariaDB 10.3+
• An active PPL customer account with a transport contract
• Enabled access to the CPL API (myAPI2) and your own map widget API key

3. Installation

1. Download the installation ZIP plg_vmshipment_semappl_X.Y.Z.zip.
2. Log in to the Joomla administration.
3. Go to System → Install → Extensions.
4. Upload the ZIP file.
5. A confirmation message appears once the plugin is installed.

Upgrade: the same procedure as installation. Joomla uses method="upgrade" and keeps all existing data and settings.

The package also contains the system plugin plg_system_semappl, which is installed and enabled automatically. It provides the PPL menu in the VirtueMart order list (see section 11).

5. Global configuration

In the plugin settings (Extensions → Plugins → click the name) fill in the parameters shared by all shipment methods built on this plugin:

Without the Client ID and Client Secret you cannot export or print labels. Without the widget API key customers will not see the map. Both are required.

Sender address

PPL requires a sender address on every shipment. The plugin takes it from the VirtueMart vendor address (Vendor → billing address), so you usually do not have to fill in anything.

The Sender address tab is there to override that — use it only if you ship from somewhere other than the shop's billing address (an external warehouse, for example). An empty field always means "take it from VirtueMart".

Check that the VirtueMart vendor address is a real Czech address. The sample address shipped with VirtueMart (Sample Company, Seattle) passes unnoticed inside VirtueMart, but PPL rejects the export with Sender.Country: Invalid value.

7. Delivery type and product code

Every method has two key parameters that must match each other.

Delivery type

PPL product code

A text field for the transport service code. It must match the delivery type:

Mismatched combinations (e.g. PRIV on a method with a map) fail on export. The list of products on your account is returned by GET /codelist/product — see section 2.

Next to it sits the PPL product code for cash on delivery field. Leave it empty — the plugin derives the COD code by itself. Fill it in only if your contract uses non-standard codes; see section 13 for details.

Other method restrictions

9. Shipping price

The resulting price is Shipment cost + Packaging fee, or 0 once the free shipping threshold is reached.

11. Bulk export

After installation, a PPL button appears in the toolbar of VirtueMart → Orders. It opens a menu with every function of the extension:

The menu is deliberately collapsed under a single button: shops commonly use several carriers, and if every extension added its own buttons the toolbar would not cope. Hovering over an item shows a short tooltip explaining what it does.

Close the menu by clicking outside it or with Esc; it closes by itself once an action starts, so that it does not cover the result.

The last item, Help, opens a panel listing every function with its description — the same text as the tooltips, only in one place. It also notes that shipments created by the extension are not visible in the PPL client portal and links to the page explaining how to obtain credentials.

Export to PPL

Sends all not yet exported orders in the chosen status as a single batch. The result is listed above the order list — shipment numbers for successes, the reason for failures. An error on one order does not stop the others.

The order status the list is taken from is set in the global configuration (Default status for export, C by default). You may list several statuses separated by commas (C,Q) — orders in any of them are then included in the batch.

Download labels

Downloads labels for every shipment that exists at PPL and is not cancelled — regardless of the order status. It is deliberately the same selection that Pending shipments shows: what is in that list gets printed.

It cannot be tied to the order status: export moves the order to the post-export status straight away, so it would drop out of the selection exactly when the label is needed.

At most 50 batches are downloaded at once, newest first. Several batches come as a ZIP — PPL cannot merge them into one PDF.

When there are no labels to download, a message says so — previously nothing visible happened.

Standalone bulk export page

If you need to switch between order statuses, open the Open bulk export link at the bottom of the plugin settings. The page does the same and adds a status filter.

13. Cash on delivery

1. Find the ID of the COD payment method: VirtueMart → Shop → Payment Methods, open the method and read virtuemart_paymentmethod_id from the URL.
2. Enter it into the Cash on delivery payment IDs parameter in the global configuration. Separate multiple IDs with commas (e.g. 3,7).

The plugin then fills in the COD amount, the order currency and the variable symbol automatically for orders using that payment.

The variable symbol may only contain digits according to PPL and is limited to 10 characters. The plugin derives it from the order number by dropping every non-numeric character and keeping the last ten. If your order numbers contain no digits at all, the internal order ID is used instead.

The product code switches itself for COD

PPL uses separate product codes for cash on delivery and rejects COD on a regular code. The plugin handles this for you: on a COD order it switches the code automatically.

If your contract uses different codes, enter the right one into the PPL product code for cash on delivery field in the shipment method settings. A filled-in field takes precedence over the automatic switch; an empty one means "switch according to the table". The actual codes of your contract are returned by the /codelist/product method.

On a method with a map also enable Cash on delivery locations only (section 8) — otherwise a customer may pick a location that does not accept COD.

A very long customer e-mail

PPL accepts 50 characters for an e-mail address. A longer one is not sent at all — a truncated address would look valid while belonging to somebody else. The plugin reports it at export time together with the order number; the shipment goes through normally, PPL just sends no e-mail notifications for it. The courier still reaches the customer by phone.

How COD looks on the label

A COD parcel carries a black "Dobirka/COD" strip along the bottom of the label. The COD amount itself is not printed — PPL keeps it in its own system and the driver sees it in the scanner.

15. Shipment overview and pickup

Shipments created by the plugin are not visible in the PPL client portal (klient.ppl.cz) — PPL confirmed on 28 August 2026 that the portal only ever shows shipments created in their own application. The overview, the state check and pickup orders therefore live here, in your shop administration.

Shipment numbers in the order list

The PPL shipment number and its last known state are shown right under the order number. A cancelled shipment is struck through in red. You no longer need to open the order detail just to see it.

Pending shipments

The Pending shipments item lists every shipment that exists at PPL and is not cancelled — that is, everything waiting to be handed over to the driver. The order status filter is deliberately not applied here: a shipment waits to be handed over regardless of what status the order has been given since.

Shipments at PPL

The Shipments at PPL item lists the shipments PPL holds on your customer account for a chosen period. Unlike Pending shipments, which reads the shop's own data, this overview asks PPL directly — and it is the only place where you also see shipments that were not created in this shop: from an earlier solution, from another shop on the same account, or entered by hand. Those rows are highlighted and flagged outside the shop.

Pick the period at the top (the last month is pre-filled) and optionally a state. The table then shows:

Below the table is the total for the whole period: how many shipments, how much the carriage cost and how much is held in cash on delivery.

The prices are PPL's real charges, not what you collected from the customer, so they can be compared against your shipping revenue. They are filled in with a delay — a fresh shipment usually has no price yet.

The Print button prints the list exactly as loaded — landscape, with the table header repeated on every page, the period at the top and the totals plus the print time at the bottom. The administration around it is not printed.

The overview loads at most 500 shipments at a time; if the period holds more, it says so and you simply choose a shorter one.

Refresh states

The Refresh states item asks PPL for the actual state of all pending shipments and stores it. Use it when something happened to a shipment outside the shop — typically when somebody cancelled it elsewhere. Such a shipment is marked as cancelled and disappears from the pending list.

States are shown in the language of the administration (waiting to be handed over, delivered, cancelled, …). You may hit a code we do not know yet — it is printed exactly as the API returned it. Tell us about it and we will add the translation.

A shipment PPL does not return will not disappear. The PPL interface answers from several servers, so a freshly created or freshly cancelled shipment may report differently for a few minutes. The plugin therefore only adds states, it never clears them — if you see a note that PPL did not return a shipment, run the check again in a moment.

Ordering a pickup

The Order pickup item opens a short form: date, number of parcels and optionally a time window and a note for the driver. The number of parcels is pre-filled from the count of shipments waiting to be handed over.

The pickup address comes from the same settings as the sender address for shipments — whatever is filled in the plugin configuration applies here too.

After submitting, the PPL pickup number is shown and the list of scheduled pickups opens. A pickup is not tied to specific shipments; it only says "come at this time for this many parcels".

⚠️ A pickup is a real transport order. Only order it once the parcels are ready.

Scheduled pickups

The Scheduled pickups item lists pickups from the last 14 days — date, PPL number, parcel count and state. A pickup that has not run yet has a Cancel button; it is confirmed by a second click so it cannot be cancelled by accident.

Only a pickup ordered from here can be cancelled — it is cancelled by the reference the plugin gave it. A pickup arranged elsewhere (by phone, in the PPL application) may still appear in the list, but without the button; cancel that one where it was created.

17. Order status after export

The plugin can move an order to a different status once it has been exported — typically a status of your own such as Handed to PPL, so you can tell at a glance which orders are done.

By default the option is empty and the plugin leaves order statuses alone.

Setting it up

1. Create the status under VirtueMart → Configuration → Order statuses. Pick a free single-letter code (T, L, M…) and a name, for example Handed to PPL.
2. Enter that code in the Order status after export parameter in the plugin's global configuration.

When the status changes

At the moment the shipment is given its number by PPL — not when the batch is sent. That distinction matters:

• An order PPL rejects keeps its original status and can be exported again.
• It works the same for exporting a single order, bulk export, and picking the number up later via Refresh status.
• An order already in the target status is not rewritten.

If you enter a status code that does not exist in VirtueMart, the plugin reports a warning and leaves the status alone — the export itself still succeeds.

Does the customer get an e-mail?

VirtueMart decides, not the plugin. Notifications go out for the statuses ticked in VirtueMart's configuration (Order statuses the shopper is notified about). A new status is not among them by default, so nothing is sent. Tick it there if you want the customer notified once the parcel is handed over.

Cancelling does not restore the status. The order stays in Handed to PPL until you move it yourself.

19. Troubleshooting

The map does not appear

1. Check that the plugin is enabled.
2. Check that the shipment method uses the Pick-up point / box delivery type, not Home delivery.
3. Check that the map widget API key is filled in.
4. Check the list of allowed domains for the key in klient.ppl.cz/widgetadmin. This is by far the most common cause — the widget simply will not load on a domain that is not listed. example.com and www.example.com are two different domains.
5. Open the browser console (F12) and look for JavaScript errors.
6. Check that no Content Security Policy blocks the www.ppl.cz domain.

If the map fails to load, the customer sees a red notice under the button saying it cannot be opened. A button that stays silent means a version older than 1.2.12.

The customer cannot complete the order

• On a method with a map the customer must choose a location. The message "Please choose a PPL pick-up point" is correct behaviour.
• On a home delivery method no location is required — in that case the problem lies elsewhere.

The shipment export fails

1. Verify the Client ID and Client Secret in the global configuration.
2. Verify that the right API environment is selected — production credentials do not work in the test environment and vice versa.
3. Verify the product code on the shipment method. It must come from your contract and match the delivery type (section 7).
4. Read the error message — the plugin shows the PPL API response including the individual invalid fields.
5. Request and response details are in the #__sema_ppl_log table.

API login fails

• Check that PPL has actually enabled CPL API access for you. A customer number alone is not enough, access is granted on request.
• Verify the credentials belong to the selected environment.
• PPL limits token issuance to 12 per minute. If you are experimenting and switching credentials, wait a moment.

The order stays in "PPL is processing the batch"

• Click Refresh status. Processing usually takes a few seconds, longer for large batches.
• If the state persists, check #__sema_ppl_log — the response will contain either InProcess or an error.

The label does not download

1. Check that the shipment has a shipment number. Without it there is no label.
2. Check that the label format matches your printer.
3. Look into #__sema_ppl_log at the response for the downloadLabel or getBatchLabel action.

For a bulk download the reason is printed straight above the order list — in red, one line per batch. If only part of it came through, the ZIP contains PRESKOCENE-DAVKY.txt listing what is missing.

The bulk export buttons do not appear

1. Check that the system plugin plg_system_semappl is installed and enabled (Extensions → Plugins, group system).
2. Check that you are on the VirtueMart → Orders page — the buttons appear nowhere else.
3. Check the browser console for JavaScript errors.
4. If SemaShipping Packeta also runs on the site, PPL must be 1.2.19 or newer and Packeta 1.4.13 or newer — see below.

The PPL button is gone and a piece of script spills out below the table

This happens only where SemaShipping PPL and SemaShipping Packeta run side by side and at least one of them is older. Both plugins insert themselves before the closing tag of the page, and in older versions they broke each other's script block while doing so; the console reports a SyntaxError.

The fix is to update both: PPL to 1.2.19 or newer, SemaShipping Packeta to 1.4.13 or newer. A newer PPL copes with an older Packeta, but it is only dependable once both are current.

Cash on delivery is not set

• Verify the payment method ID in the Cash on delivery payment IDs parameter. It must match virtuemart_paymentmethod_id from the payment method URL.
• Separate multiple IDs with commas and no spaces.
• Verify that your PPL account has COD enabled and that the chosen product supports it.
• If the export ends with "Unable to get shipment number" (MyApi2.Error.UnableToGetShipmentNumber), the order data is not at fault: your PPL account has no shipment number range assigned for COD products. Ask your PPL sales representative for one, quoting your customer number.

The shipment method does not appear in the cart

• Check the country settings (allowed and blocked).
• Check the weight limits.
• Check that the method is Published in VirtueMart and the plugin is Enabled.