Shipping with Qapla’ for OpenCart — pickup points, labels and carrier tracking (Italy)

Shipping with Qapla’ for OpenCart (OpenCart 4.x, 3.x and 2.3) connects the shop to Qapla’, the Italian shipping and tracking platform. At checkout the buyer picks a courier pickup point (punto di ritiro), and the order goes to Qapla’ with one button, with the recipient, the parcel, the products and the chosen point. Pro adds labels, automation by status, tracking in the order and an e-mail to the buyer with the tracking number.

What you need from Qapla’. A Qapla’ channel with a private API key (the Qapla’ panel → Settings → Channels → your channel → Configure → Channel → Private API Key). API access depends on your Qapla’ plan, and the pickup point search is switched on by Qapla’ support on request. Qapla’ plans are paid separately. The key is stored encrypted and is never shown on the page again.

What the buyer gets

The checkout (the stock one and CatCode One Page Checkout) shows the delivery methods you set up: a courier of your channel, to the address or to a pickup point. Under a “to a pickup point” method a panel opens: the buyer sees the points by the post code (CAP) of their address, can type another CAP or a town, and sees the name, address, distance and opening hours. An order without a chosen point cannot be placed: the server checks it, not only the page.

The delivery address of the order becomes the address of the point, so it goes that way to the admin, the invoice and the e-mails. A PTI (Poste Italiane) point does not take cash on delivery, and that combination is refused with an explanation. A point is accepted only from the server’s own search, and an invented identifier is refused. Search results are cached for 6 hours and searches are limited to 20 per 10 minutes per session, so the shop stays under the Qapla’ limit of 150 calls a minute per channel. The buyer interface is Italian when the shop is Italian and English otherwise.

What the admin gets

Extensions → Extensions → Shipping → Shipping with Qapla’ has six tabs: “Delivery methods”, “Qapla’ account”, “Orders”, “Labels and tracking”, “Journal” and “Licence”. On “Qapla’ account” you paste the API key and press “Save and check the connection”: the module shows the name of the channel and the couriers connected to it (for example BRT, GLS, Poste Italiane), and the page reloads with the lists for setting up the methods. The “Try it” box searches points by courier, country and CAP, so you see what the buyer will see, and if Qapla’ answers with an error its text is shown on the spot.

On “Delivery methods” you set up to eight methods: a courier of the channel (with contract variants such as BRT-V1), to the address or to a pickup point, a title, a price (fixed), free from an amount, a maximum weight, countries, a geo zone and a tax class. The “Qapla’ orders” button leads to the list of Qapla’ orders with the filters “Not sent to Qapla’”, “Without a label” and “On the way”.

The order gets a “Qapla’” panel: the courier, the chosen point and the “Send to Qapla’” button (the recipient, province, amount, cash on delivery, products with SKUs, weight and size, the point). Sending again updates the order in Qapla’. An order with another delivery method goes with the courier you choose, or with the default courier. The point can be found and changed in the order, and the text of a Qapla’ refusal lands in the panel and in the order history as one line.

What Pro adds

In Pro the “Create label” button creates the shipment and the label from the order: PDF, JPG or ZPL to download, a return label and label removal (Delete label). One label is active per order: a double click does not duplicate it, and a shipment in the pending state is read again later by the module. The test mode (“sandbox”) creates labels without booking.

Automation: you choose the order statuses on which the order is sent to Qapla’ and on which the label is created. Tracking arrives from the Qapla’ webhook (its address is shown on the “Labels and tracking” tab, and the channel key is checked in the request itself) and from an hourly check; the “Refresh tracking” button updates it by hand. The Qapla’ status “delivered” (99) moves the order to the status you chose, and returns (95) are added as a row. The buyer gets one e-mail with the number and a tracking link.

The list of Qapla’ orders has bulk actions: send to Qapla’ (up to 100 orders in one call), create labels (up to 50), download all labels as one ZIP and refresh tracking. The journal shows the last 300 calls to Qapla’ and webhooks. Pro also has courier rules for orders with other methods (by country, weight and method), price by weight and a cash-on-delivery surcharge.

How it works, step by step

1. Install the archive for your OpenCart version and install the module in Extensions → Extensions → Shipping.
2. In the Qapla’ panel copy the private API key of the channel.
3. On the “Qapla’ account” tab paste the key and press “Save and check the connection”: the channel name and the couriers appear.
4. On “Delivery methods” add the methods: the courier, to the address or to a pickup point, the price.
5. Place a trial order: at checkout choose a “to a pickup point” method and a point from the list.
6. Open the order in the admin and press “Send to Qapla’”, then continue in the Qapla’ panel.

Under the hood

• Qapla’ API 1.3 and 1.2 (api.qapla.it): getChannel, getCouriers, getPudos, pushOrder, createLabel, getLabel, deleteLabel, getShipment, trackingByTimeFrame and the Qapla’ webhook. The channel key is encrypted and appears neither in the log nor on pages.
• Pickup points come from getPudos by CAP, and their opening hours are composed in the language of the buyer (lun/mar/sab or Mon/Tue/Sat). A point that did not come from the server’s own search is not accepted.
• A label is created under a database lock, so a double click does not create two shipments; a shipment in the PENDING state is not created again.
• On OpenCart 3 and 2.3 the tracking check runs from a cron address, and on OpenCart 4 through the OpenCart scheduler; the webhook is a separate address of the module.
• Settings stay after the module is installed again; on removal the history and Qapla’ order tables are not erased.
• The interface is in English and Italian.

How to install

1. Extensions → Installer: upload the archive for your version without renaming it (OpenCart 4: cc_qapla.ocmod.zip, 3.x: cc_qapla-oc3.ocmod.zip, 2.3: cc_qapla-oc23.ocmod.zip; for 2.3 copy the contents of upload/ to the shop root).
2. For 3.x and 2.3: Extensions → Modifications → Refresh.
3. Extensions → Extensions → Shipping → Shipping with Qapla’: install the extension and open the settings.
4. On the “Qapla’ account” tab paste the channel key and press “Save and check the connection”.
5. On “Delivery methods” add the delivery methods and save.
6. For Pro: enter the key or start the trial on the “Licence” tab.