VibeFox Servientrega for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 5.0 or later, installed and active. The plugin refuses to activate without it.

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

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_servientrega folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Servientrega, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

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 (see Configuration).

6. Optionally add fixed prices per country and weight and a fallback cost.

7. Add VibeFox Servientrega to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones and choose countries.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox Servientrega. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:

Title (zone): the name customers see for this zone. Leave it empty to use the global Method title.

Every time you save the settings, the cached Servientrega quotes and the login token are cleared. 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.

General

Enable/Disable: turns the method on or off in all zones at once.

Method title: the shipping method name shown in the cart and at checkout. A zone can override it. Default: Servientrega.

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

User (login): your Servientrega / SISCLINET user.

Password: your Servientrega / SISCLINET password, as you type it. The plugin has it encrypted by the Servientrega web service before login, as the official Servientrega client does.

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.

Mercancía Premier (parcels; billed weight at least 3 kg): the default. The volumetric weight is 222 kg per m³.

Mercancía Industrial (heavy goods): the volumetric weight is 400 kg per m³.

Documento unitario (documents): for documents.

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

Currency conversion rate: Servientrega quotes in COP. If your store 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. Leave it empty if your store currency is COP. If your store uses another currency and this field is empty, live rates are not used and the fixed prices apply. The plugin 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. When it is empty and your store address in WooCommerce > Settings > General is in Colombia, the municipality of the store 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 store currency. Click + Add country to add a row and the cross 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.

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.

Per order (weight tier of the whole cart): the price of the weight column that matches the cart weight, charged once.

Per item (weight tier of each product × quantity): the price of each product's weight column, multiplied by its quantity and added up. The fallback cost is multiplied by the number of items.

Live Servientrega rates are always per shipment.

Conditions

Minimum weight (kg): hide the method when the cart weighs less. 0 means no limit.

Maximum weight (kg): hide the method when the cart weighs more. Default: 50. 0 means no limit.

Minimum order amount: show the method 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. It applies only where the method has a price: a table price or the fallback cost (then no request goes to Servientrega), or a live rate. Leave empty to never offer free shipping.

Excluded shipping classes: hide the method when the cart contains a product from any of these WooCommerce shipping classes.

Tax status: Taxable adds WooCommerce tax to the shipping cost, None does not. Servientrega quotes (ValorTotal) already include the carrier's charges. Choose None if you do not want to add tax on top.

Availability without shipping zones

Ignore shipping zones: offer Servientrega for the countries below even if the method is not added to any shipping zone.

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

Advanced

Debug log: writes rate calculations and API errors to the WooCommerce log: WooCommerce > Status > Logs, source vfd_servientrega. Credentials, tokens and customer addresses are not logged. Turn the log off when you are done.

Remove data on uninstall: when on, deleting the plugin removes all Servientrega settings, zone methods and cached quotes. Deactivating the plugin never deletes anything.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin first checks the conditions: delivery country, cart weight, minimum order amount and excluded shipping classes. 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. If free shipping applies, the method is shown with a price of 0.

For a destination in Colombia with credentials set, the plugin 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 plugin then sends Servientrega one piece per order: the total weight converted from your store 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, and the plugin converts it to your store 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.

If there is no live rate, the price comes from the fixed price table, then from Fallback cost. If neither applies, the method is hidden. The customer never sees an API error. The reason is written to the debug log.

The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS). Spanish translations (Colombia, Spain) are included.

The plugin 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. Ecuador, Peru, Panama and international shipments use the fixed prices.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox Servientrega. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Servientrega is not shown to customers at checkout. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Servientrega does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). Check the weight limits, Minimum order amount and Excluded shipping classes. Without a live rate, check that the country or * Default has a price, or that Fallback cost is set.

Live rates do not appear: turn on Debug log, reload the checkout and open WooCommerce > Status > Logs, source vfd_servientrega. 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, 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 plugin waits 10 minutes before the next try. Save the settings to try again at once.

The customer's city is not recognised: the department and city are matched against the built-in DANE table. For rare spellings, the customer can type the 8-digit DANE code as the postcode. Developers can map it with the vfd_svtg_dane_code filter.

Rates look outdated after a change: save the settings page. This clears the cached Servientrega quotes and the token.

For developers: the filters vfd_svtg_quote_request and vfd_svtg_default_dimensions adjust the quote request and the dimensions of products without them. vfd_svtg_api_base and vfd_svtg_soap_url change the endpoints, for example if Servientrega gives you another server.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. Settings, zone methods, cached quotes and tokens are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

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