VibeFox Balikobot for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Balikobot account (for live rates and pickup points): you need a Balikobot account with API access. The API user and API key are in the Balikobot client zone (client.balikobot.cz). Balikobot support (podpora@balikobot.cz) activates the API for your account and carriers. Live rates need a carrier and service for which Balikobot supports "transportcosts". Pickup points need a carrier with "branchlocator" support (for example Česká pošta, Zásilkovna, PPL, DPD, GLS). Ask Balikobot support if unsure. Fixed prices work without an account.

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

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Balikobot in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Enter the API user and API key, choose the carrier and service type, the price source and the country prices (see Configuration). For pickup services, turn on Pickup point selection. Click Save.

On install the module creates the Balikobot carrier with the delivery time text Delivery by Balikobot. The carrier is assigned to the zones of Czechia, Slovakia and Hungary and to all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Balikobot > Configure. Each section has its own Save button, which saves the whole page. After saving you see Settings saved. Cached rates and pickup points were cleared. Warnings about settings that would hide the carrier, the live rates or the pickup points are shown at the top of the page: live rates or pickup points without the API user or API key, a shop currency other than CZK without Exchange rate, empty Country prices with fixed prices or the fallback, a shop weight unit the module does not know (weights are then read as kg; use kg, g, lb or oz) and a deleted carrier. A value that is not a number is not saved, and you see a warning with the field name.

General

Enable/Disable: turns Balikobot shipping on or off. This is the same switch as the carrier status in Shipping > Carriers.

Name: the shipping method name shown to customers (the carrier name). Default: Balikobot. Required, at most 64 characters.

Tax status: None, or Taxable with one of your tax rules. With a tax rule, its tax is added to the shipping price. The choice is saved to the carrier. Balikobot prices are usually without VAT. Default: None.

Balikobot API account (needed for live rates and pickup points)

API user: your Balikobot API user from the client zone.

API key: your Balikobot API key from the client zone. After saving, the field stays empty and shows Saved - leave empty to keep it. Clear the API user to remove the saved key. Type a new value only to change it.

Carrier: the Balikobot carrier used for rates and pickup points: Česká pošta (default), Zásilkovna (Packeta), PPL, DPD, GLS, DHL Express, UPS, TNT, FedEx, Geis, InTime, Uloženka, Toptrans, Pošta bez hranic, Slovenská pošta, SPS (Slovak Parcel Service) or Magyar Posta. It must be activated in your Balikobot account.

Service type: the Balikobot service code of the carrier. Default: NP. For Česká pošta: NP = parcel to a post office, NB = parcel to Balíkovna, DR = home delivery. The codes of other carriers are listed in the Balikobot client zone and API documentation.

Price (all prices are in your shop default currency)

Price source: how the price is calculated.

Country prices: a table of 2-letter country codes (for example CZ, SK) and prices. Click Add row to add a country and the trash icon to remove one. Use * as the country code for all other countries. Decimals with a dot or a comma. Used in the fixed mode and as the API fallback. A country without a price (and without a * row) gets no fixed rate. Invalid rows are removed when you save, and a warning lists them.

Fixed price per: Order charges the price once. Item (price x quantity) multiplies it by the number of items in the cart. This applies to fixed prices only. A live Balikobot rate is always for the whole package.

Exchange rate: the value of 1 unit of the Balikobot price currency (usually CZK) in your shop default currency, for example 0.04. Used only when Balikobot returns a price in a different currency. Leave it empty to reject such prices, so a customer is never charged a wrong price.

Conditions

Min weight (kg): hide the carrier when the cart is lighter. 0 means no limit. Product weights are converted from your shop weight unit.

Max weight (kg): hide the carrier when the cart is heavier. Default: 100. 0 means no limit. An empty field means 100 kg. If Min weight (kg) is greater than the maximum, you see a warning and the previous weights are kept.

Minimum order amount: show the carrier only from this cart subtotal (after discounts, without tax). Leave empty to always show it.

Free shipping: turn on free shipping from the amount below.

Free shipping from: the cart subtotal (after discounts, without tax) from which shipping is free. No API request is made in that case.

Availability without shipping zones

Normally the carrier is offered in its zones in Shipping > Carriers.

Ignore shipping zones: offer the carrier in the countries below even if it is not linked to their zone. The module links the carrier to all zones, also to zones you create later. When you switch the option off, the zones added this way are removed again. Your own zones stay.

Countries: the destination countries for that mode. Leave empty to use all countries you ship to. Used only with Ignore shipping zones.

Pickup points

Pickup point selection: the customer must choose a pickup point. Use it for pickup services, for example Česká pošta NP or NB, or Zásilkovna. Needs the API user and API key.

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

Advanced

Debug log: logs API requests and rate calculations to logs/vfd_blkb_debug.log.php in the module folder. The file cannot be opened from the web. API errors are always logged. Credentials and customer addresses are never logged. Turn the log off when you are done.

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

Remove data on uninstall: when on, uninstalling the module deletes the module settings and the carrier. Uninstalling without this option never deletes data. Pickup points saved in orders are kept.

How it works at checkout

At the shipping step PrestaShop asks the module for the Balikobot price. Only physical products count: virtual products add no weight and are not included in the order amount. The module first checks the countries (with Ignore shipping zones), the cart weight and Minimum order amount. If free shipping applies, the price is 0 and no request goes to Balikobot.

In the fixed mode the price is taken from Country prices. In the live modes the module sends Balikobot the carrier, the service type, the destination country and postcode, and the cart weight in kg. A live rate is requested only when the delivery address has a postcode. A price in another currency is converted with Exchange rate, or rejected if no rate is set. The price is calculated in your default currency and then shown in the customer's cart currency.

Live prices are cached for 1 hour, so the same cart does not trigger a new request. A failed request is cached for 5 minutes, and the API timeout is 12 seconds, so the checkout does not wait for Balikobot on every refresh. API errors are never shown to the customer: the carrier is hidden, or the fixed price is used in the fallback mode. The details go to the debug log.

If you edit the carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.

The module does not create shipments in Balikobot, print labels or order pickups: order the shipment in the Balikobot client zone. It does not track parcels or update order statuses. One carrier and one service type are used for all zones. Pickup points are shown as a drop-down list, without a map.

Pickup points

With Pickup point selection on, a list of pickup points appears under the Balikobot carrier in the delivery step. The list is loaded from the Balikobot "branchlocator" for the country, city and postcode of the delivery address. Until the address has a city, the customer sees Enter your city to see the pickup points. The list is cached for 12 hours.

The choice is saved to the cart as soon as the customer picks a point. It is required: Continue in the delivery step and Place order are blocked with Please select a pickup point. The server also checks that the chosen point belongs to the delivery address. Otherwise the customer sees The selected pickup point is not available for your shipping address. Please choose a pickup point again. If no points are found, the customer is asked to check the city and postcode or choose another shipping method. If the points cannot be loaded, the customer is asked to try again later or choose another shipping method.

The chosen pickup point is saved in the order. On the back office order page it is shown in the Balikobot pickup point block, with the Balikobot branch ID and the carrier, which you need when you create the shipment in Balikobot. Click Change to choose another point near the order address and click Save. Changing the point needs only the right to edit orders, not access to the Modules pages. If an order has no point, the block shows No pickup point was selected for this order.

The customer sees the point as Pickup point: on the order confirmation page and in the order details. In the order confirmation e-mail and in the new order e-mail for the shop (Mail alerts module) it is added after the carrier name. Existing orders keep their pickup point data.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Balikobot is the first block on Modules > Module Manager > VibeFox Balikobot > Configure, 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 shop. Below them are the line Product: presta-shipping-balikobot and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (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 shop 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 main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the Balikobot carrier is not shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

Balikobot does not appear at checkout: check that the license is active and Enable/Disable is on. Read the warnings at the top of the module page. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group, or turn on Ignore shipping zones and check Countries. Check the weight limits and Minimum order amount. In the fixed mode, check that the country or * has a price. Products can also be limited to certain carriers in the product page.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field on the module page. It shows the reason: missing API credentials, no postcode yet, the Balikobot error for the carrier and service (for example authorization failed, check the API user and API key), or a price in another currency without Exchange rate. With Live Balikobot rate, fixed price if the API fails customers still get the fixed price while you fix the problem.

Prices are in the wrong currency: fixed prices are in your shop default currency. Balikobot returns live prices in the currency of your Balikobot contract (usually CZK). If it differs from your default currency, set Exchange rate.

Is VAT included: Balikobot prices are usually without VAT. With Tax status set to a tax rule, PrestaShop adds shipping tax.

No pickup points in the list: check that the API user and key are set, that the carrier supports "branchlocator" and that the delivery address has a city and postcode. Check the log for the Balikobot error.

Rates or pickup points look outdated after a change: click Save on the module page. This clears the cached rates and pickup points.

The page says the Balikobot carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.

For developers: the module has its own hooks to change the API address (actionVfdBlkbApiUrl), the "transportcosts" package (actionVfdBlkbTransportcostsPackage) and the number of pickup points (actionVfdBlkbPickupMaxResults, default 30).

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Balikobot and choose Uninstall. The license key, the license status, the cached rates and the pickup points are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history), and the settings, the log and pickup points of carts without an order are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again (or Reset) gives the saved carrier its status from before the uninstall: on stays on, off stays off. Pickup point data saved in orders is never deleted.

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