VibeFox DHL Packstation for Adobe Commerce — Ayuda

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.

Checkout: the location picker is made for the standard Magento checkout (Luma and Blank themes). Third-party checkouts (for example Hyvä or one-step checkouts) need their own integration.

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

DHL API key: the list of locations comes from the free DHL Location Finder API. Register on the DHL developer portal (developer.dhl.com), create an app, add the "Location Finder - Unified" API and copy the app's API key. No DHL business contract is needed for this API. Without the key the method is hidden at checkout. Mind the request limit of your DHL app: every new postcode or city search is one API request.

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-dhl-packstation-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/DhlPackstationShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_DhlPackstationShipping 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 script and styles), then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox DHL Packstation. 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. Paste the DHL API key, click Save Config, then click Test API key. Choose the location types and enter the country prices (see Configuration). Set Enable DHL Packstation shipping to Yes and click Save Config.

The module adds the DHL Packstation shipping method to Magento. Customers see it as DHL Packstation - Pickup location (method title and method name). It is off after installation (Enable DHL Packstation shipping = No). By default it is offered for Germany and Austria, the countries of the default price list.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox DHL Packstation, 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. Every change of the settings clears the cached location searches. Amounts and weights accept "4.99" and "4,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title; a 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 Search radius (meters) or Max results that is not a whole number; a price, an amount or a weight that is not a number or is negative; a Min weight (kg) greater than the Max weight (kg).

Warnings at the top of the group tell you when the DHL API key is empty, when no location type is enabled (in both cases the method is not shown at checkout) and when entries of Country prices are not in the CC:PRICE format (these entries are listed and ignored).

General

Enable DHL Packstation shipping: shows or hides the method at checkout. Default: No.

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

Method name: shown after the method title, as "Method title - Method name". Default: Pickup location. At most 64 characters; an empty field saves the default.

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

DHL Location Finder API

DHL API key: the "API Key" of your app on developer.dhl.com. Without it the method is hidden at checkout. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete the saved key, clear the field and click Save Config.

Connection test: the Test API key button searches the locations near 53113 Bonn with the saved key and clears the location cache. Save the settings first. It shows how many locations were found, that DHL rejected the key (401/403), or that the API did not answer correctly (details in the debug log).

Pickup locations

At checkout the customer sees the locations near their shipping postcode and can search another postcode or city.

Location types: which DHL locations the customer can choose: Packstation (parcel locker), Post Office (Postfiliale) and DHL Parcel Shop (Paketshop). All three by default. If none is selected, the method is hidden. For a Packstation the customer must enter their DHL Postnummer.

Search radius (meters): the radius around the searched postcode or city. Default: 5000. A whole number; values below 100 or above 25000 m (the DHL maximum) are moved to that limit, an empty field saves the default.

Max results: the maximum number of locations shown per search. Default: 20. A whole number; DHL allows up to 50, larger values are reduced to 50.

Use the chosen location as the order's shipping address: on by default. Address line 1 of the order's shipping address becomes for example "Packstation 105" (or "Postfiliale 502" for a post office or parcel shop), line 2 "Postnummer" with the number, plus the postcode, city and country of the location, so labels printed from the order go to the right place. Name, company and phone come from the customer's address; the region is emptied. Only the address of the order changes, not the customer's address book.

Prices

Prices are in the base currency of your store, tax excluded. If your store taxes shipping, Magento adds the tax class set in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. Magento shows the price in the customer's currency.

Country prices: the price per destination country, format CC:PRICE, separated by commas or new lines. Default: DE:4.99, AT:5.99. A decimal comma also works (DE:4,99).

Other countries: the price for a destination country that is not in Country prices. Default: 5.99. Leave it empty to hide the method for such countries.

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

Free shipping from: the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) from which this shipping is free. Leave empty for never free.

Availability

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

Max weight (kg): the method is hidden above this cart weight. Default: 31.5, because a Packstation takes parcels up to 31.5 kg. 0 means no limit.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs).

Minimum subtotal: show the method only if the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) is at least this value. Leave empty to always show it.

Ship to Applicable Countries: All Allowed Countries offers the method for every country your store allows (General > Country Options), Specific Countries (default) only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries. Default: Germany and Austria.

Advanced

Debug log: writes checkout steps and API requests to var/log/vfd_dhlp_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. The API key, the Postnummer and customer addresses are never written.

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 settings, the log and the locations of unfinished checkouts (see Uninstall). The license key and the cached searches are always removed. The chosen locations stay in the orders.

How it works at checkout

At the shipping step Magento asks the module for the DHL Packstation price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module checks that an API key and at least one location type are set, the cart weight and the minimum subtotal; Magento checks the countries. The module then takes the price for the destination country (or the price for other countries) and applies free shipping if the subtotal is high enough. A Magento cart price rule with free shipping also makes the price 0. No request goes to DHL for the price: it does not depend on the location.

The module does not create DHL shipments, print labels or track parcels. Use the DHL business customer portal or a label tool: with Use the chosen location as the order's shipping address on, the order already contains the Packstation address and Postnummer. The module does not calculate live DHL rates and shows no map. There is no manual entry of a Packstation number.

Pickup points

When the customer selects DHL Packstation, a DHL pickup location box appears under the shipping methods. The DHL locations near the postcode and city of the shipping address are loaded. DHL is asked only once the DHL Packstation method is selected. The customer can type another postcode or city and click Search (or press Enter). Locations are grouped by type (Packstation, Post Office, Parcel Shop) and show their distance. If nothing is found, the customer sees No DHL locations found near "…". Try another postcode or city. If the shipping address changes, the list follows it, unless the customer searched on their own.

For a Packstation the customer must enter the DHL Postnummer, their 6-12 digit DHL customer number from the DHL app or DHL account. For other locations it is optional. The choice is saved to the cart as soon as it is made, and a reload of the checkout keeps it. On Next the checkout and then the server check it again: the location must be one of the DHL search results in the shipping country. Without a location the customer sees Please choose a DHL Packstation or post office for delivery. and stays on the shipping step. A missing Postnummer for a Packstation is reported with Please enter your DHL Postnummer - it is required for delivery to a Packstation., a wrong one with The DHL Postnummer must consist of 6 to 12 digits.

Search results are cached for 12 hours. An empty or failed search is cached for 10 minutes, so the checkout does not wait for DHL on every refresh. The API timeout is 12 seconds. If the DHL API cannot be reached, the customer sees DHL locations cannot be loaded right now. Please try again later or choose another shipping method. A location the customer had already chosen is still accepted.

When the order is placed, the location (ID, type, number, name, address) and the Postnummer are saved with the order. The shipping description of the order becomes for example DHL Packstation - Pickup location - DHL pickup location: Packstation 105, … - DHL Postnummer: 12345678. This text is shown on the order confirmation page, in the order in the customer account, in the order e-mails and on invoices. If Use the chosen location as the order's shipping address is on, the order's shipping address is replaced by the address of the location. If the customer cancels the payment on the payment provider's page and Magento returns the cart, the customer can choose a DHL location again and continue; the cancelled order keeps the location it was placed with.

On the admin order page (Sales > Orders > View, Information tab) the DHL pickup location block shows the location, its type and ID, and the Postnummer. Click Change, search by postcode or city in the country of the customer's address, choose another location, change the Postnummer and click Save location. You can also change only the Postnummer. The shipping description and, if Use the chosen location as the order's shipping address is on, the shipping address of the order are updated. Each change adds the order comment DHL pickup location changed to: …, which is not sent to the customer. Changing the location needs the Admin right to edit orders; access to the configuration is not needed. The block also works for older orders and when the module is switched off. An order with DHL Packstation but without a location (for example created in the Admin) shows No DHL location was selected for this order.; choose a location there before you save a Postnummer.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox DHL Packstation is the first row of the VibeFox DHL Packstation 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-dhl-packstation 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 DHL Packstation 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: the DHL pickup location block and Change keep working.

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

DHL Packstation does not appear at checkout: check that the license is active and Enable DHL Packstation shipping is Yes for the website of the store. Check that the DHL API key is filled in and at least one location type is selected (the warnings at the top of the group tell you). Check Ship to Applicable Countries and Ship to Specific Countries, that the destination country has a price (or Other countries is set), and that the weight and subtotal rules do not hide it.

No locations are shown: click Test API key. If DHL rejects the key (401/403), check the key and that your app has the "Location Finder - Unified" API. Turn on Debug log, reload the checkout and look at the Log field in the Advanced section. Check that the request limit of your DHL app is not reached.

No locations near an address: increase Search radius (meters) or Max results, or let the customer search another postcode or city. A Packstation without a number in the DHL data is not listed.

The customer sees "Enter your postcode or city to see DHL locations near you.": the shipping address has no postcode and no city yet. The customer can type one into the search field.

Change on the admin order page says "Please choose a DHL location of the search - nothing was changed.": search by postcode or city and choose a location from the results. If the order has no location yet, a location must be chosen before the Postnummer can be saved. Each order keeps its own location, also when several orders were placed from one cart, and it can be changed on each of them.

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_DhlPackstationShipping. It removes the data and the code.

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

The license key, the license status and the cached searches are always removed. If Remove data on uninstall is Yes, the settings, the log and the locations of carts without an order are removed too. If it is No, the settings are kept for a re-install. The chosen locations always stay with the orders, and the shipping description and address of the orders do not change.

DHL and Packstation are trademarks of their respective owners. This module is not affiliated with or endorsed by DHL.