VibeFox Servientrega for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

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

Servientrega account (for live rates only): live rates use the Servientrega Cotizador Corporativo (corporate quoting API). You need a Servientrega corporate (credit) account with access to it. You need three values: the user, the password and the billing code (código de facturación, usually starting with SER). They are your SISCLINET credentials and are issued by your Servientrega commercial advisor. If you only use fixed prices, you do not need a Servientrega account.

Server access (for live rates only): your server must be able to reach web.servientrega.com over HTTP on port 8058 (quoting API) and port 8081 (password encryption web service).

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 Servientrega 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. For live rates, enter the user, password and billing code, choose the Servientrega product, enter the origin DANE code and, if your shop currency is not COP, the currency conversion rate. Click Add Colombian departments if your shop has none yet (see Configuration).

5. Optionally add fixed prices per country and weight and a fallback cost, then click Save.

On install the module creates the Servientrega carrier with the delivery time text Servientrega courier delivery. The carrier is assigned to all zones and 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 Servientrega > Configure. They apply to every zone. Each section has its own Save button, which saves the whole page. Every save clears the cached Servientrega quotes and the login token.

If live rates cannot work with the saved settings, a warning above the form tells you why: a missing user, password or billing code, a missing conversion rate, or a missing origin DANE code. A warning also appears if the weight or dimension unit of your shop (International > Localization, Local units) is not known to the module; weights are then read as kg and dimensions as cm. When you save, a value that is not a number, a negative number, a conversion rate of 0, a minimum weight above the maximum weight, a wrong price in the table or a method title longer than 64 characters is refused with an error, and nothing is saved.

General

Enable Servientrega: turns the carrier on or off in all zones at once. This is the same switch as the carrier status in Shipping > Carriers.

Method title: the carrier name shown to the customer in the cart and at checkout. Default: Servientrega. Required, at most 64 characters.

Servientrega API (live rates for Colombia) (optional; without credentials only the fixed prices are used)

User (login): your Servientrega / SISCLINET user. Clearing it also removes the saved password.

Password: your Servientrega / SISCLINET password, as you type it. The module has it encrypted by the Servientrega web service before login. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Billing code: the código de facturación of your Servientrega account, shown in SISCLINET. It usually starts with SER.

All three fields are needed for live rates. Live rates are requested only for destinations in Colombia. Other countries use the fixed prices.

Servientrega product: the service of your Servientrega agreement that is quoted.

The billed weight is the larger of the real and the volumetric weight.

Currency conversion rate: Servientrega quotes in COP. If your shop default currency is not COP, enter the value of 1 COP in your shop currency, for example 0.00023. The declared parcel value is converted to COP the same way. Leave it empty if your shop currency is COP. If your shop uses another currency and this field is empty, live rates are not used and the fixed prices apply. The module does not fetch exchange rates. Both a point and a comma are accepted as the decimal separator.

Colombian departments: the department helps to tell apart municipalities with the same name. PrestaShop has no Colombian departments by default; without them only city names that are unique in Colombia are recognised. Click Add Colombian departments to add the 33 departments as states of Colombia (ISO codes ANT, DC…), turn on Contains states for Colombia and add the department field to the Colombian address form. Departments that already exist are not added twice. When everything is in place, the field shows how many departments Colombian addresses have.

Ship from (used for live rates)

Origin city (DANE code): the 8-digit DANE code of the municipality you ship from, for example 11001000 Bogotá, 05001000 Medellín, 76001000 Cali or 08001000 Barranquilla. A 5-digit municipality code is also accepted. When it is empty and your shop address in Shop Parameters > Contact > Stores is in Colombia, the municipality of the shop address is used.

Fixed prices (used when there is no live rate: no credentials, a destination outside Colombia, an unknown municipality, a missing conversion rate, or an API error or no coverage for the route)

Price per country: a table of countries and prices in your shop default currency, tax excluded. Click Add country to add a row and the trash icon to remove one. Price applies to any weight. The weight columns XS ≤1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg and XL >5 kg replace it for that weight when they are above 0. The row * Default applies to all countries without their own row. A row without any price is not saved.

Fallback cost: used when there is no live rate and no row of the table matches. Leave it empty to hide the carrier in that case.

Fixed price applies: how fixed prices are charged.

Live Servientrega rates are always per shipment.

Conditions

Minimum weight: hide the carrier when the cart weighs less, in kg. 0 means no limit.

Maximum weight: hide the carrier when the cart weighs more, in kg. Default: 50. 0 means no limit.

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

Free shipping from: delivery is free when the cart subtotal (after discounts, before tax) reaches this amount, and no request goes to Servientrega. It applies to every destination where the carrier is offered, also to countries without a row in the price table. Leave empty to never offer free shipping.

Tax: the tax rule of the carrier, or No tax. Servientrega quotes (ValorTotal) already include the carrier's charges. Choose No tax if you do not want to add tax on top.

Availability without shipping zones

Normally the carrier is offered in the zones assigned to it in Shipping > Carriers.

Ignore shipping zones: offer Servientrega for the countries below even if the carrier is not assigned to their zone. The carrier is then assigned to all zones, also to zones you create later. Turning the option off gives the carrier its previous zones back.

Countries: the destination countries for that mode. Leave empty to use all active countries of your shop. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: writes rate calculations and API errors to logs/vfd_svtg_debug.log.php in the module folder. The file cannot be opened from the web. Credentials, tokens and customer addresses are not logged. When the log is off, nothing is written, API errors included. Turn the log off when you are done.

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

Remove data on uninstall: when on, uninstalling the module deletes all Servientrega settings, the carrier, cached quotes and logs. Past orders keep their carrier. When off, everything is kept for a re-install.

How it works at checkout

At the shipping step PrestaShop asks the module for the Servientrega price. Only physical products count: virtual products add no weight and are not included in the order amount. The module first checks the conditions: the delivery country (with Ignore shipping zones), cart weight and minimum order amount. If free shipping applies, the price is 0 and no request goes to Servientrega. Then it looks for a price: the live Servientrega rate, then the price table, then the fallback cost. If there is no price, the carrier is hidden for that cart.

For a destination in Colombia with credentials set, the module finds the DANE code of the customer's municipality. It uses a DANE code typed as the postcode or in the city field, or matches the department and city against the built-in table of about 1,130 municipalities. Accents and "D.C." are ignored. A city name that exists in only one department is found even without the department.

The module then sends Servientrega one piece per order: the total weight converted from your shop unit to kg, and a box with the length and width of the largest item and the total volume of all items, converted to cm. Products without dimensions count as 10 × 10 × 10 cm. The declared value is the cart subtotal converted to COP, at least 6,000 COP. Servientrega returns the total in COP. The module converts it to your shop default currency, and the customer sees it in the cart currency.

The login token is kept until it expires, at most 4 days. A rejected token is renewed once automatically. Each quote is cached for 1 hour per route and parcel, so the same cart does not trigger a new request. A failed request (encryption, login or quote) is cached for 10 minutes, so the checkout does not wait for Servientrega on every refresh. The timeout is 10 seconds per request.

The customer never sees an API error. The reason is written to the debug log when it is on.

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 calculates rates only. It does not create guides (guías), labels or stickers, request pickups, track or cancel shipments, or let customers choose a Servientrega office (Centro de Soluciones). Create the guide in SISCLINET or your Servientrega portal. Cash on delivery (logística de recaudo) is not quoted. Live quotes are for domestic shipments within Colombia only. Other countries use the fixed prices.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Servientrega is the first block on Modules > Module Manager > VibeFox Servientrega > 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-servientrega 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 Servientrega carrier is not shown to customers at checkout and no rate is requested or 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

Servientrega does not appear at checkout: check that the license is active and Enable Servientrega is on. 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. Without a live rate, check that the country or * Default has a price, or that Fallback cost is set. 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. Common reasons: a missing conversion rate (shop currency is not COP), no origin DANE code, the customer's department or city is not entered yet or is not a known municipality, wrong credentials, or no coverage for the route. Fixed prices cover these cases if you set them.

Login fails: check the user, password and billing code with your Servientrega commercial advisor. After a failed login the module waits 10 minutes before the next try. Save the settings to try again at once.

The customer's city is not recognised: click Add Colombian departments so that customers can choose their department. For rare spellings, the customer can type the 8-digit DANE code as the postcode.

Rates look outdated after a change: click Save on the module page. This clears the cached Servientrega quotes and the token.

The page says the Servientrega 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 hooks actionVfdSvtgDaneCode and actionVfdSvtgQuoteRequest let you change the destination DANE code and the quote request.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Servientrega and choose Uninstall. The license key and the license status are always removed. The cached quotes, tokens and the encrypted password are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings and log are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again, or Reset, gives the carrier back the status it had before.

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