SemaShipping PPL

A PPL shipping plugin for VirtueMart. Customers pick a PPL pick-up point, ParcelBox or AlzaBox from a map right in the cart; the shop then exports shipments straight into PPL (one by one or in bulk) and prints labels — no retyping into the PPL customer portal.

2. Credentials from PPL

The plugin uses two independent sets of credentials. Do not mix them up — each is obtained elsewhere and serves a different purpose.

Client ID and Client Secret (CPL API)

These are not self-service — you cannot generate them in the customer portal. Ask your PPL sales representative (or customer support) to enable OAuth 2.0 access to the CPL API (myAPI2) and issue your client credentials. Include your PPL customer number and mention that this is an e-shop integration using SemaShipping PPL, an approved solution by Semakin.cz — PPL has the solution on record, which speeds the request up.

• Credentials for production and for the test environment are separate. If you want to test first, ask for both at once and mention that this is an e-shop integration.
• The plugin keeps the access token and only renews it once it expires (30 minutes of validity). PPL allows just 12 issued tokens per minute, which is why the token is not requested on every call.

Map widget API key

This one you create yourself:

1. Log in to klient.ppl.cz/widgetadmin with the same credentials as the PPL customer portal.
2. Create a new widget and generate an API key for it — it starts with the ak_ prefix.
3. Add the domains the map is allowed to load on.

Mind the domains. The widget loads only on domains explicitly listed for the key. Wildcards (*) do not work yet, and example.com and www.example.com count as two different domains — add both. If you test on a staging domain or a subdomain, add that one too.

Product codes

The product code determines the service used to send the parcel and depends on your contract with PPL. It is set per shipment method (see section 7).

The most common codes:

The actual list of products on your account is returned by GET /codelist/product in the CPL API. If you are unsure, ask your PPL sales representative which products you have contracted.

Check these first

• Your VirtueMart vendor address is complete — the plugin sends it to PPL as the sender address, and PPL rejects a shipment without one.
• Your account has cash on delivery enabled, if you plan to offer it.

4. Enabling the plugin

After installation the shipment plugin must be enabled manually:

1. Go to Extensions → Plugins.
2. Search for semappl or PPL.
3. Click the name SemaShipping PPL – parcel shipping (DHL Group) for VirtueMart (group vmshipment) and set Status = Enabled.
4. Save.

The system plugin plg_system_semappl enables itself during installation — you do not need to switch it on.

The plugin alone shows nothing on the storefront. Shipping appears only once you create a shipment method in VirtueMart (see section 6).

6. Creating a shipment method

One plugin installation can back any number of shipment methods — typically one for pick-up points and one for home delivery.

1. In the VirtueMart administration go to Shop → Shipment Methods.
2. Click New.
3. Fill in:
   • Shipment Name: the name customers see (e.g. "PPL — pick-up point")
   • Published: Yes
   • Shipment Method: choose SemaShipping PPL – parcel shipping (DHL Group) for VirtueMart
4. Switch to the Configuration tab.
5. Set the parameters from the following sections.
6. Save.

8. Pick-up point map

The plugin uses the PPL map widget 2.0. It opens as an overlay after clicking the "Choose a pick-up point" button.

Map settings per method

What the plugin stores from the selection

The location code, name, type (ParcelShop / ParcelBox / AlzaBox) and address. The code is what goes to PPL; the rest is for display — to the customer in the order summary, to you in the administration.

The selection survives cart changes

The chosen location is kept in the session. When the customer changes the payment, the shipping method or the cart contents, the selection stays. It is cleared once the order is placed.

Widget version 1.x is discontinued on 31 August 2026. This plugin uses version 2.0 exclusively, so the end of support does not affect you — just remember that the ak_… key is mandatory for version 2.0.

10. Exporting shipments to PPL

How PPL processes shipments

Unlike most carriers, PPL accepts shipments in batches and processes them in the background. The plugin submits a batch, receives its identifier and then asks PPL whether it is finished. This usually takes a few seconds.

That is why an order has three possible states in the administration:

Exporting a single order

1. Open the order in VirtueMart → Orders.
2. In the shipping panel click Create shipment in PPL.
3. Once finished, the shipment number and the label button appear.

If you see a message that PPL is still processing the batch, wait a few seconds and click Refresh status.

What gets sent to PPL

• The order number as the shipment reference
• Recipient name and address, phone, e-mail
• For a business order the company goes on the first line and the person's name becomes the contact
• The pick-up location code (for methods with a map)
• The order number once more as the external number (code CUST) — PPL prints it on the label and passes it on to invoicing
• Cash on delivery, when the order is a COD order
• The customer note

The sender address is always sent — PPL rejects a request without it. The plugin takes it from the VirtueMart vendor and the global configuration can override it.

When the export fails

The error message from PPL is shown right in the administration. A shipment PPL rejects does not exist on their side, so the order returns to the not exported state and you can retry once the data is fixed.

12. Printing labels

A single shipment

The Download label button in the order detail.

Several shipments at once

The Download labels button in the order list. What you get depends on how many batches the shipments came from:

• Orders from one batch → a single file with all labels.
• Orders from several batches → a ZIP archive with one file per batch.

PPL cannot merge labels across batches into one file. If you want to print in one go, export the orders together — one export run is one batch.

Print settings

The format, page size and starting position live in the global configuration (section 5). With A4 four labels fit on a sheet; Starting position 1–4 lets you print onto a sheet you have already peeled labels off.

14. Cancelling a shipment

A shipment that will not go into transport — the customer cancelled the order, the goods are out of stock, the export was a mistake — has to be cancelled in PPL. This is not optional housekeeping: once the shipment data exists, PPL keeps it on the books as waiting to be handed over until you cancel it.

Only a shipment you have not physically handed over to the driver can be cancelled.

A single order

1. Open the order in VirtueMart → Orders.
2. In the shipment panel click Cancel shipment in PPL.

Instead of the label the panel then shows Cancelled with a date and time. Cancelling is irreversible — the shipment cannot be revived, only replaced by a new one.

Several orders at once

In the order list tick the orders you want to cancel and click Cancel in PPL in the toolbar. The button then asks Really cancel (count)? — only the second click performs the cancellation. The question disappears if you do not click within six seconds.

Orders without a PPL shipment are skipped, so you do not have to untick them. The result is printed above the list, per order.

Bulk cancellation deliberately does not work off the status filter the way bulk export does. Cancelling is irreversible, so only the orders you actually tick get cancelled.

Creating a new shipment after cancelling

For a cancelled order the shipment panel offers Create a new shipment. Use it when the parcel does go out after all — typically after fixing the address or the pick-up point. The original shipment number disappears from the order; it stays traceable in the PPL communication log.

What PPL returns

Cancellation is asynchronous on PPL's side: the API confirms receipt immediately, but the shipment flips to Cancelled in their system only after a while. That is why the plugin only records the date and time on success — if the cancellation did not go through on PPL's side, you will find out from their system, not from the shop administration.

16. Uninstalling

1. Extensions → Manage → Extensions
2. Search for semappl.
3. Uninstall the shipment plugin SemaShipping PPL – parcel shipping (DHL Group) for VirtueMart.

What gets deleted

• The shipment plugin (PHP, JS, CSS, language files)
• The system plugin plg_system_semappl (removed automatically)
• The #__virtuemart_shipment_plg_semappl table (shipment data attached to orders)

What stays

• The #__sema_ppl_log table — audit records of the communication with the PPL API

Why is the log kept? It documents what was sent to PPL and when. You can drop it manually:

DROP TABLE IF EXISTS `#__sema_ppl_log`;

(replace #__ with your actual table prefix)

Go-live checklist

• CPL API access requested from PPL support and approved
• Client ID and Client Secret filled in
• API environment matches the issued credentials
• Widget API key created at klient.ppl.cz/widgetadmin
• Shop domains added to the widget API key (including the www variant)
• Default sender address configured in the PPL customer portal
• Plugin installed and enabled
• Shipment method created in VirtueMart and published
• Delivery type chosen
• Product code filled in and matching the delivery type
• Map country and location types configured
• Cash on delivery payment IDs filled in (if you offer COD)
• Label format and page size chosen
• Default status for export configured
• Test order placed and the shipment exported successfully
• Label downloaded and printed
• Bulk export tried out in the order list

PPL® is a registered trademark of PPL CZ s.r.o., a DHL Group company. This product is an independent extension and is not affiliated with, or endorsed by, PPL CZ s.r.o. or DHL Group.