VibeFox Balikobot for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_balikobot-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_balikobot.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_balikobot-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Balikobot and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

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

5. 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. Turn on Enable/Disable and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_balikobot.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Balikobot, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 and 5 for OpenCart 3. The settings page and its fields are the same in both versions.

On install the extension creates a table for the pickup points of checkouts and orders. The method is off until you turn on Enable/Disable and save. If you install the extension again after an uninstall, the Balikobot settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Balikobot > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. After saving you see Settings saved. Cached rates and pickup points were cleared. Only admin users with the modify permission for this extension can save the settings.

Some errors stop the save, and nothing is saved: an empty or too long Name, a Sort Order that is not a whole number, or an unknown tax class or geo zone. Other problems are shown as warnings, and the rest of the settings is saved: a value that is not a number (or is negative) is not saved and the warning names the field; invalid Country prices rows are removed and listed.

Warnings about settings that would hide the method, 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 store currency other than CZK without Exchange rate, empty Country prices with fixed prices or the fallback, and a store without a weight class with the unit kg (product weights are then read by their unit name: kg, g, lb or oz).

General

Enable/Disable: turns Balikobot shipping on or off at checkout. Default: off.

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

Sort Order: the position of the method in the list of shipping methods. A whole number.

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 store default currency)

Price source: how the price is calculated.

Country prices: a list of countries and prices. Click Add row to add a row and the remove button to delete one. Choose * All other countries for every country without its own row. 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, so the method is hidden for it.

Fixed price per: Order (default) 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 store 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 method when the cart is lighter. 0 means no limit (default). Product weights are converted from their OpenCart weight class.

Max weight (kg): hide the method 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 method only from this cart subtotal (after coupons, without tax). Leave it empty to always show it.

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

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

Tax Class: the tax of this class is added to the shipping price. Balikobot prices are usually without VAT. Default: --- None ---.

Availability

Normally the method is offered in the geo zone selected here (All Zones means everywhere). Ignore geo zone offers it in the countries of the list instead.

Geo Zone: offer the method only for addresses in this geo zone. Geo zones are managed in System > Localisation > Geo Zones.

Ignore geo zone: offer the method in the countries below, whatever the geo zone.

Countries: the destination countries for that mode. Leave it empty to allow all countries. Used only with Ignore geo zone.

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 storage/logs/vfd_blkb_debug.log.php. The file cannot be read from the web. API errors are always logged. Credentials and customer addresses are never logged. Turn the log off when you are done. When the file reaches 5 MB, it is moved to vfd_blkb_debug.old.log.php and a new log is started.

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 extension deletes the settings, the log and the pickup points of checkouts without an order. When off (default), the settings are kept. Pickup points saved in orders are always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API key is not exported.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved API key is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Balikobot price. If a Geo Zone is set (and Ignore geo zone is off) and the address is outside it, Balikobot is not offered. With Ignore geo zone the Countries list decides. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The extension then checks the cart weight and Minimum order amount. The order amount is the price of the products that need shipping, after the coupon discount and before tax. 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 extension 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, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax Class.

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 method is hidden, or the fixed price is used in the fallback mode. The details go to the debug log.

The extension 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 change order statuses. One carrier and one service type are used for all destinations. Pickup points are shown as a drop-down list, without a map.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Balikobot in the window Shipping method options. The method works the same way as on OpenCart 3; the pickup point list is described in Pickup points.

Pickup points

With Pickup point selection on, a list of pickup points appears under the Balikobot method in the Delivery Method step of the OpenCart checkout. 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. While the list loads, the customer sees Loading pickup points.... The list is cached for up to 12 hours.

The choice is saved as soon as the customer picks a point. It is required: Continue in the delivery step is refused 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 Balikobot cannot be reached at that moment, a point already chosen is accepted. 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.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page. The window Shipping method options shows the pickup point list under the Balikobot method, with the same texts and checks. The list is loaded every time the window opens, because the address can change on the same checkout page, and comes from the cache when possible. If the customer clicks Continue in the window without a valid point, the message is shown at the top of the checkout page and the window stays open. OpenCart 4 keeps one order for the checkout and updates it at every confirmation; the pickup point of the order is updated with it.

The chosen point is added to the shipping method of the order as - Pickup point: followed by its name and address. The customer sees it on the order pages of their account and in the order e-mails, and it is printed on the invoice.

On the admin order page (Sales > Orders, View) the Balikobot pickup point panel shows the point, its Balikobot ID and the carrier, which you need when you create the shipment in Balikobot. Click Change, choose another point near the order address and click Save. The shipping method text of the order is updated too, and you see Pickup point updated. Changing the point needs only the modify permission for orders, not access to the extension settings. If an order has no point, the panel shows No pickup point was selected for this order. The panel also works while Balikobot is disabled: existing orders keep their pickup point data, and you can still change the point.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Balikobot is the first block on Extensions > Extensions > Shipping > VibeFox Balikobot > Edit, 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: opencart-shipping-balikobot and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Balikobot is not shown to customers at checkout and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees the method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 extension page. Check Geo Zone (or Ignore geo zone and Countries), the weight limits and Minimum order amount. In the fixed mode, check that the country or * All other countries has a price. Check that the products have Requires Shipping set to Yes.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field on the extension 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 store 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 a Tax Class selected, OpenCart 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 extension page. This clears the cached rates and pickup points.

The page says "Warning: You do not have permission to modify VibeFox Balikobot!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_balikobot (OpenCart 3) or extension/vfd_balikobot/shipping/vfd_balikobot (OpenCart 4) in System > Users > User Groups.

For developers: the Balikobot API address can be replaced with the setting vfd_blkb_api_url (for tests); it has no field on the settings page.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox Balikobot. The license key and license status of this extension are always removed. OpenCart always resets Enable/Disable, Sort Order, Tax Class and Geo Zone. The cached rates and pickup points are always removed, and the pickup point panel and checkout list stop working. If Remove data on uninstall is on, the settings, the log and the pickup points of checkouts without an order are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. Pickup point data saved in orders is never deleted, and the shipping method text of existing orders keeps the pickup point.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Balikobot in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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