VibeFox Servientrega for Adobe Commerce — 帮助

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4. Live rates use the cURL extension.

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 module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-servientrega-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/ServientregaShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_ServientregaShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox Servientrega. Paste your VibeFox license key into License key in the license block, the first row of the group, 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 the base currency of your store is not COP, the currency conversion rate. Optionally add fixed prices per country and weight and a fallback cost (see Configuration). Set Enable to Yes and click Save Config.

The module adds the Servientrega shipping method to Magento. Customers see it as Servientrega - Courier delivery (method title and method name). It is off after installation (Enable = No).

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Servientrega, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Method title and Method name also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. When a Servientrega setting has changed, saving also clears the cached Servientrega quotes, the login token and the encrypted password. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title or Method name, longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a number field that does not contain a non-negative number; a conversion rate of 0; a Minimum weight (kg) greater than the Maximum weight (kg); a price in the table that is not a non-negative number.

While Enable is Yes and at least one of the user, password and billing code is filled in, warnings after saving tell you why live rates cannot work: a missing user, password or billing code, a missing conversion rate when the base currency of your store is not COP, or no origin DANE code and no Colombian shipping origin address. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

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

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

Method name: shown after the method title, as "Method title - Method name". Default: Courier delivery. Required, at most 64 characters.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

Servientrega API (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. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved password, type a new value to change it. To delete the saved password, clear the field and click Save Config.

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: the value of 1 COP in the base currency of your store, for example 0.00023. Servientrega quotes in COP; the quote is converted to the base currency with this rate, and the declared parcel value is converted to COP the same way. It is required for live quotes when the base currency is not COP. If it is empty in that case, live rates are not used and the fixed prices apply. Not needed when your base currency is COP. No exchange-rate service is contacted.

Colombian addresses in Magento already have a department (State/Province) list, so customers can choose their department. The department helps to tell apart municipalities with the same name. The module does not change the Magento lists of countries and regions.

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 the shipping origin of your store (Stores > Configuration > Sales > Shipping Settings > Origin) is in Colombia, the municipality of that 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 and weight: a table of countries and prices in the base currency of your store, tax excluded. Click Add country to add a row and Delete to remove one. Base applies to any weight. The weight columns XS (up to 1 kg), S (up to 2 kg), M (up to 3 kg), L (up to 5 kg) and XL (over 5 kg) replace it for that weight when they are above 0; an empty or zero column uses Base. The row * All other countries applies to all countries without their own row. If a country is in the table twice, the last row wins. 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 when the cart weighs less. Empty or 0 means no limit.

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

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

Free shipping from: delivery is free when the cart 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 empty to never offer free shipping.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs).

The module has no tax field. Shipping tax is set for the whole store in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. Servientrega quotes (ValorTotal) already include the carrier's charges. Leave shipping untaxed if you do not want to add tax on top.

Availability

Ship to Applicable Countries: All Allowed Countries offers Servientrega for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries. Live rates are requested for Colombia only; other countries use the fixed prices.

Advanced

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

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the Servientrega settings and the log (see Uninstall). The license key and the cached quotes are always removed. Orders are never changed.

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

How it works at checkout

At the shipping step Magento asks the module for the Servientrega price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the order amount. The module first checks the countries, the cart weight and Minimum order amount. If free shipping applies, the price is 0 and no request goes to Servientrega. A Magento cart price rule with free shipping also makes the price 0, after the same checks. 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 module finds the DANE code of the customer's municipality. It uses a DANE code typed as the ZIP/postal code 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 in kg and a box built from the items. Magento products have no standard dimensions, so every item counts as a 10 × 10 × 10 cm box. 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 base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.

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. Expired cache entries are removed by the Magento cron.

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

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 row of the VibeFox Servientrega group in Stores > Configuration > Sales > Delivery Methods, 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: magento-shipping-servientrega and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Delivery Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 method is not shown to customers at checkout and no rate is requested or calculated. The Magento storefront does not know that you are logged in to the Admin, so the method 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Servientrega does not appear at checkout: check that the license is active and Enable is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum order amount. Without a live rate, check that the country or * All other countries has a price, or that Fallback cost is set.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Debug log viewer in the Advanced section. Common reasons: a missing conversion rate (base 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. Saving a changed Servientrega setting clears this wait at once.

The customer's city is not recognised: the customer should choose the department in State/Province. For rare spellings, the customer can type the 8-digit DANE code as the ZIP/postal code.

Rates look outdated after a change: the cached quotes and the token are cleared when you save a changed Servientrega setting on the Delivery Methods page. Otherwise a cached quote is used for up to 1 hour.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

For developers: the Magento events vfd_svtg_dane_code and vfd_svtg_quote_request let an observer change the destination DANE code and the quote request (in the transport object). An error in such an observer does not break the checkout.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_ServientregaShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_ServientregaShipping to remove the data, then bin/magento module:disable Vibefox_ServientregaShipping, delete the folder app/code/Vibefox/ServientregaShipping and run bin/magento setup:upgrade.

The license key, the license status, the cached quotes, tokens and the encrypted password from the Servientrega web service are always removed. If Remove data on uninstall is Yes, the Servientrega settings and the log are removed too. If it is No, the settings and the log are kept for a re-install. Orders and their shipping method are never changed.

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