VibeFox DPD Pickup for Adobe Commerce — 帮助

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

Checkout: the pickup point selector is made for the standard Magento checkout (Luma and Blank themes). Other checkouts, for example one-step checkout modules, are not supported.

DPD Baltic credentials (Lithuania, Latvia, Estonia): the pickup point list comes from the DPD Baltic web service. You need the API username and password that DPD gives to its business customers. Ask your DPD account manager or the DPD customer service of your country. One account lists the pickup points of Lithuania, Latvia and Estonia.

DPD Slovakia: the public DPD Slovakia parcelshop search needs no credentials.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-dpd-pickup-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/DpdPickupShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_DpdPickupShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy (the module has its own checkout scripts and styles), then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox DPD Pickup. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Choose your DPD API. For DPD Lithuania, Latvia or Estonia enter the API username and password. Check the prices per country and the countries you ship to. Set Enable DPD Pickup to Yes and click Save Config. Then click Refresh pickup points to check the connection (see Configuration).

The module adds the DPD Pickup shipping method to Magento. Customers see it as DPD Pickup - Point or locker (method title and method name). It is off after installation (Enable DPD Pickup = No) and offered for Slovakia, Lithuania, Latvia and Estonia.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox DPD Pickup, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Method title and Method name also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached pickup point lists. Amounts and weights accept "3.50" and "3,50".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title or Method name, longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a Min weight (kg) greater than the Max weight (kg).

Other problems are reported as warnings after saving. A value that is not a number, or a negative number, in an amount or weight field is not saved: the field becomes empty and the warning names it. Lines of Country prices that are not in CC:PRICE format are listed in a warning and ignored. A Notices row at the top of the group tells you when the DPD Baltic username or password is empty, or when no prices are set. Both mean the method is not shown at checkout.

General

Enable DPD Pickup: shows or hides DPD Pickup at checkout. Default: No.

Method title: the carrier name shown in the cart and at checkout. Default: DPD Pickup. Required, at most 64 characters.

Method name: shown after the method title, as "Method title - Method name". Default: Point or locker. Required, at most 64 characters.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

DPD pickup point list

Pickup points are loaded from DPD and cached for 24 hours.

DPD API: the DPD company your account is with. Baltic accounts use the web service of their own country.

API username (Baltic): your DPD Baltic web service username. Not needed for DPD Slovakia. Clearing it also clears the saved password.

API password (Baltic): your DPD Baltic web service password. Not needed for DPD Slovakia. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved password, type a new value to change it. To delete the saved password, clear the field (or the username) and click Save Config.

Pickup points: the Refresh pickup points button clears the cache and loads the pickup points from DPD now: Lithuania, Latvia and Estonia for the Baltic API, a test search in Bratislava for DPD Slovakia. It shows the number of pickup points or the error per country. It uses the saved settings of the website chosen in Scope, so click Save Config first.

Prices

Shipping prices are fixed per country, in the base currency of your store, tax excluded. Magento shows the price in the customer's currency. DPD prices are not requested from the API. The module has no tax setting: if your store charges tax on shipping, set the tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.

Country prices: one line per country: CC:price, for example EE:3.50. A decimal comma is accepted. Default: SK:3.50, LT:4.00, LV:4.00, EE:4.00.

Fallback cost: the price for countries that are not in Country prices. Default: 5.00. Leave it empty to offer the method only in the listed countries.

Calculation type: Per order charges the price once. Per item (price x quantity) multiplies it by the number of items in the cart.

Free shipping from: shipping is free when the order subtotal (products that need shipping, after discounts, before tax, in the base currency) reaches this amount. Leave empty to turn it off.

Availability

The method is also hidden when DPD returns no pickup points for the customer's address or the DPD API cannot be reached, because an order cannot be delivered without a pickup point.

Min weight (kg): the minimum cart weight. Empty or 0 means no limit.

Max weight (kg): heavier carts do not see the method. Default: 31.5. Empty or 0 means no limit. Check the parcel limits of DPD Pickup points and lockers in your country.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). Magento products have no standard dimensions, so volumetric weight is not calculated.

Minimum subtotal: show the method only when the order subtotal (after discounts, before tax, in the base currency) is at least this amount. Leave empty to always show it.

Ship to Applicable Countries: All Allowed Countries offers DPD Pickup for every country your store allows, Specific Countries only for the countries below. After installation: Specific Countries.

Ship to Specific Countries: the destination countries for Specific Countries. After installation: Slovakia, Lithuania, Latvia and Estonia.

Pickup point selector

City order: show major cities first (Tallinn, Riga, Vilnius, Bratislava and others). Default: Yes.

City list width: the CSS width of the city list, for example 100% or 300px. Default: 100%.

Pickup point list width: the CSS width of the pickup point list, for example 100% or 400px. Default: 100%.

Advanced

Debug log: writes API requests and checkout steps to var/log/vfd_dpd_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors are always logged, even when this is off. Credentials are never logged.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the DPD Pickup settings, the log and the pickup points of carts that never became an order (see Uninstall). The license key and the cached pickup point lists are always removed. The pickup points saved in orders are always kept.

How it works at checkout

At the shipping step Magento asks the module for the DPD Pickup price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. Magento checks the countries; the module checks the cart weight and the minimum subtotal, takes the price for the country (or the fallback cost) and applies free shipping if the subtotal is high enough. A Magento cart price rule with free shipping also makes the price 0. Then the module loads the DPD pickup points for the address. If DPD returns none, cannot be reached or the Baltic credentials are missing, the method is hidden. The customer never sees an API error. The reason is written to the log.

A pickup point list is cached for 24 hours, an empty list for 1 hour. A failed request is remembered for 5 minutes, so a DPD outage never slows down the checkout. The API timeout is 15 seconds. With DPD Slovakia the method is shown while the city or postcode is still missing, and the points are loaded once the customer has entered them.

The module does not request DPD prices, create DPD shipments, print labels, create manifests, order courier pickups, track parcels or show a map. Only the DPD Baltic web service and the DPD Slovakia parcelshop search are supported.

Pickup points

When the customer selects DPD Pickup, a city list (City) and a pickup point list (DPD pickup point) appear under the shipping methods. The points are loaded for the country, city and postcode of the shipping address, and loaded again when the customer changes them. The city of the customer's address is pre-selected. The choice is saved to the cart as soon as the customer selects it, and a reload of the checkout keeps it. With DPD Slovakia, the customer sees Enter your city and postcode to see the DPD pickup points nearby. until the address is complete, then the points nearby. If DPD has no points for the address, the customer sees No DPD pickup points are available for this address right now. Please check the address or choose another shipping method.

A pickup point is required. Without one the customer cannot click past Next and sees Please select a DPD pickup point. The server checks again that the point belongs to the DPD list for the shipping address. A forged or outdated choice is refused with The selected DPD pickup point is not available for this address. Please choose another one. If the DPD list cannot be loaded at that moment, the point the customer had already chosen is accepted.

When the order is placed, the point is saved with the order and added to its shipping description, for example DPD Pickup - Point or locker - DPD pickup point: followed by the point name, street, postcode and city. This text is shown on the order confirmation page, in the order in the customer account, in the order e-mails and on invoices. The name saved in the order comes from DPD, not from the browser.

On the admin order page (Sales > Orders > View, Information tab) the DPD pickup point block shows the point name, its ID and country. Click Edit, choose a city and another point and click Save. The point must be in the DPD list for the shipping address of the order. The page shows Pickup point updated. or Pickup point not found for the order address. The shipping description of the order is updated, and the order comment VibeFox DPD Pickup: pickup point changed from "…" to "…". is added without notifying the customer. Changing the point needs the Admin right to edit orders; access to the configuration is not needed. With DPD Slovakia the order needs a shipping city and postcode to change the point.

The block also shows the point of older orders when the module is switched off. Edit is available only while the method is enabled and DPD returns the list. An order with DPD Pickup but without a point (for example created in the Admin) shows No pickup point was selected for this order., and the debug log has an error for it. Choose the point there with Edit, or give it to DPD by hand.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox DPD Pickup is the first row of the VibeFox DPD Pickup group in Stores > Configuration > Sales > Delivery Methods, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-shipping-dpd-pickup and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Delivery Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the DPD Pickup method is not shown to customers at checkout and no rate is calculated. The Magento storefront does not know that you are logged in to the Admin, so the method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

DPD Pickup does not appear at checkout: check that the license is active and Enable DPD Pickup is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits, Minimum subtotal and that the country has a price (or a fallback cost). Check the Notices row of the group and click Refresh pickup points: without pickup points for the address the method is hidden.

An error after Refresh pickup points: the result shows the DPD error per country. For example, "Login failed" means DPD rejected the Baltic credentials, so no pickup point can be loaded. Check the API username and password with DPD.

DPD Slovakia shows no points: the points appear once the customer has entered the city and postcode. DPD lists only the points within 50 km of that address. Developers can change the radius with the Magento event vfd_dpd_sk_search_radius.

Finding the reason: turn on Debug log, reload the checkout and look at the Log field in the Advanced section. Every decision is written there. API errors are always logged. API usernames and passwords are never written to the log.

Pickup points look outdated after a change: click Save Config or Refresh pickup points. Both clear the cached lists. Flush Magento Cache in System > Cache Management clears them too.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_DpdPickupShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_DpdPickupShipping to remove the data, then bin/magento module:disable Vibefox_DpdPickupShipping, delete the folder app/code/Vibefox/DpdPickupShipping and run bin/magento setup:upgrade.

The license key, the license status and the cached pickup point lists are always removed. If Remove data on uninstall is Yes, the DPD Pickup settings, the log and the pickup points of carts without an order are removed too. If it is No, the settings are kept for a re-install. The pickup points saved in orders are never deleted, and the shipping description of the orders does not change.

DPD is a trademark of its respective owner. This module is not affiliated with or endorsed by DPD.