VibeFox Servientrega 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.

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

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_servientrega-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_servientrega.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_servientrega-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 Servientrega 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. For live rates, enter the user, password and billing code, choose the Servientrega product, enter the origin DANE code and, if your store currency is not COP, the currency conversion rate.

6. Optionally add fixed prices per country and weight and a fallback cost, turn on Enable Servientrega and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_servientrega.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 Servientrega, click Install (the green + button), then Edit (the pencil button).

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

After install the method is off until you turn on Enable Servientrega and save. If you install the extension again after an uninstall, the Servientrega settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Servientrega > Edit. The sections are listed on the left. They apply to every geo zone. One Save button at the bottom saves the whole page without reloading it. Every save clears the cached Servientrega quotes and the login token. Only admin users with the modify permission for this extension can save the settings.

If live rates cannot work with the saved settings, a warning above the settings 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 store has no kg weight class or cm length class and its default unit is not known to the extension; 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, a method title that is empty, longer than 64 characters or contains < > ; = # { }, or a sort order that is not a whole number is refused with an error, and nothing is saved.

General

Enable Servientrega: shows or hides Servientrega at checkout. Default: off.

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

Sort order: the position of Servientrega among the shipping methods at checkout. A whole number.

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 extension 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 store default currency is not COP, enter the value of 1 COP in your store currency, for example 0.00023. The declared parcel value is converted to COP the same way. If your store currency is COP, the field says no conversion is needed: leave it empty. If your store uses another currency and this field is empty, live rates are not used and the fixed prices apply. The extension does not fetch exchange rates. Both a point and a comma are accepted as the decimal separator.

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. The OpenCart store address is free text, so the origin is never taken from it: without this field there are no live rates.

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 store default currency, tax excluded. Click Add country to add a row and the remove button to delete one. Price applies to any weight. The weight columns XS (up to 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) and XL (over 5 kg) replace it for that weight when they are above 0. The row * Default applies to all countries without their own row. A new row starts as * Default. 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 method in that case.

Fixed price applies: how fixed prices are charged.

Live Servientrega rates are always per shipment.

Conditions

Minimum weight (kg): hide the method below this cart weight. 0 means no limit (default).

Maximum weight (kg): hide the method above this cart weight. Default: 50. 0 means no limit.

Minimum order amount: show the method only when the subtotal of the products that need shipping (after the coupon, before tax) reaches this amount. Leave it empty to always show it.

Free shipping from: delivery is free when that subtotal reaches this amount, and no request goes to Servientrega. It applies to every destination where the method is offered, also to countries without a row in the price table. Leave it empty to never offer free shipping.

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

Geo zone: offer Servientrega only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. It is not checked when Ignore shipping zones is on.

Availability without geo zone

Normally the method is offered in the geo zone selected in Conditions, or everywhere.

Ignore shipping zones: offer Servientrega for the countries below whatever the geo zone.

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

Advanced

Debug log: writes rate calculations and API errors to storage/logs/vfd_svtg_debug.log.php. The file cannot be read from the web. Credentials, tokens and customer addresses are not logged. When the log is off, nothing is written, API errors included. When the file reaches 5 MB, it is moved to vfd_svtg_debug.old.log.php and a new log is started. 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 extension deletes all Servientrega settings and the log. When off (default), they are kept for a re-install. Cached quotes are always deleted.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The password 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 password is kept while the user is set.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Servientrega price. If a Geo zone is set and the address is outside it, Servientrega is not offered (unless Ignore shipping zones is on). Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The order amount is the price of these products after the coupon discount and before tax. Gift certificates and reward points are not taken into account. The extension 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 method is hidden for that cart.

For a destination in Colombia with credentials set, the extension 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. The department is the Region / State of the address: OpenCart already has all 33 Colombian departments. Accents and "D.C." are ignored. A city name that exists in only one department is found even without the department.

The extension then sends Servientrega one piece per order: the total weight converted from the product weight class 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 order amount converted to COP, at least 6,000 COP. Servientrega returns the total in COP. The extension converts it to your store default currency and rounds it to its decimals. The customer sees it in their currency with the tax of the selected Tax class.

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.

The extension 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. It adds nothing to orders: the order shows the method title and the shipping cost like any other OpenCart shipping method.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Servientrega in the window Shipping method options, where the method title is shown with the price. The method works the same way as on OpenCart 3.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Servientrega is the first block on Extensions > Extensions > Shipping > VibeFox Servientrega > 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-servientrega 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, the Servientrega shipping method is not shown to customers at checkout and no rate is requested or 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

Servientrega does not appear at checkout: check that the license is active and Enable Servientrega is on. Check Geo zone, 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. 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. Common reasons: a missing conversion rate (store 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, no coverage for the route, or the server cannot reach web.servientrega.com on ports 8058 and 8081. 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 extension waits 10 minutes before the next try. Save the settings to try again at once.

The customer's city is not recognised: the customer should choose the department in the Region / State field. 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 extension page. This clears the cached Servientrega quotes and the token.

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

For developers: the OpenCart events vfd_servientrega/dane_code and vfd_servientrega/quote_request let another extension change the destination DANE code and the quote request.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox Servientrega. The license key and license status of this extension are always removed. OpenCart always resets Enable Servientrega, Sort order, Tax class and Geo zone. The cached quotes, tokens and the encrypted password are always removed. If Remove data on uninstall is on, the other settings and the log are deleted as well. If it is off, they are kept and are used again when you install the extension again. Existing orders keep their shipping method and cost.

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 Servientrega in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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