VibeFox Correos CityPaq 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.

Delivery to Spain: CityPaq lockers exist only in Spain, so the method is offered only for delivery addresses in Spain.

Correos API credentials (for the live locker list only): the Correos CityPaq list reads the active lockers from the Correos "terminals" API. On the Correos developer portal, open the "terminals" API and use Request access for your application. Correos approves requests from its business customers and sends a client ID and a client secret. They are also shown under My applications on the portal. If customers enter the locker themselves or choose from your own list, you do not need API credentials.

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_correos_citypaq-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_correos_citypaq.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_correos_citypaq-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 Correos CityPaq 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. Fill in the price table, choose how the customer selects the locker (see Configuration), turn on Enable/Disable and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_correos_citypaq.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 Correos CityPaq, 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.

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

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Prices and amounts accept a decimal comma or a decimal point. Only admin users with the modify permission for this extension can save the settings.

Warnings at the top of the page tell you when the price table has no row for Spain and no default row, when the chosen locker selection cannot work (no lockers in your list, no API credentials), what the last Correos API error was, and when the store has no weight class with the unit kg (product weights are then converted by the unit name: kg, g, lb or oz; unknown units are read as kg; check System > Localisation > Weight Classes). If the name is empty, invalid or longer than 64 characters, a weight or an amount is not a valid number of 0 or more, Min weight (kg) is greater than Max weight (kg), or Sort order is not a whole number, the page shows an error and nothing is saved. Invalid prices in the price table, duplicated rows and invalid or duplicated lines in My lockers are reported as warnings, and the rest is saved.

General

CityPaq lockers exist only in Spain, so the method is never offered for other countries.

Enable/Disable: turns Correos CityPaq shipping on or off. Default: off.

Name: the shipping method name shown to the customer at checkout. Default: Correos CityPaq. Required, at most 64 characters, without < > ; = # { }.

Tax class: OpenCart adds the tax of this class on top of the prices from the table. No tax means the prices are final.

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

Prices (the section title shows your store default currency)

Correos does not publish a rate API for CityPaq, so the price comes from this table. Enter your Correos contract prices in the store default currency, tax excluded.

Price table: a row for Spain (ES) and/or a default row * Default. Each row has a base Price and optional prices for the parcel sizes XS (up to 1 kg), S (up to 2 kg), M (up to 3 kg), L (up to 5 kg) and XL (above 5 kg). A size price of 0 or empty uses the base price. Click Add row to add a row and the × button to remove one. Without a matching row the method is hidden. If a country appears twice, only the first row is used.

Calculation type: how the parcel size is found.

Per order (size by the total cart weight): one price for the whole cart, chosen by the total weight. This is the default.

Per item (size by each item weight, multiplied by quantity): each product gets the price of its own size, multiplied by its quantity, and the prices are added up.

Product weights are converted to kg from the weight class of each product.

Conditions

Min weight (kg): hide the method when the cart is lighter. 0 means no limit.

Max weight (kg): hide the method when the cart is heavier. Default: 30, because CityPaq accepts parcels up to 30 kg. 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

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

Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) from which this method costs 0. Used only when Free shipping is on.

CityPaq locker selection

The section has a link to the official Correos CityPaq finder.

Locker selection: how the customer chooses the locker before placing the order. Default: the customer enters the locker.

Customer chooses from the Correos CityPaq list (Correos API, credentials below): the customer sees the active CityPaq lockers of the postal code of the delivery address and can search another 5-digit postal code. When a postal code has no locker, the lockers of the same area, then of the same province are listed, nearest postal codes first (up to 50). If the list cannot be loaded or finds nothing, the customer enters the locker instead.

Customer enters the locker (code or address from the Correos finder): a required field for the locker code (for example S0000213D) or address, 3 to 120 characters, with a link to the Correos CityPaq map.

Customer chooses from my list of lockers (below): a required drop-down of the lockers from My lockers. Lockers near the customer's postal code are listed first.

Do not ask for a locker: no locker question at checkout.

If you choose the Correos list without API credentials, or your own list while My lockers is empty, customers are asked to enter the locker instead.

Correos CityPaq list (API) (used only with the Correos CityPaq list)

The section has a link to the "terminals" API page on the Correos developer portal. Only the list of lockers is read. Prices always come from the price table.

API client ID: the client_id of your application on the Correos developer portal.

API client secret: the client_secret of your application on the Correos developer portal.

After saving, both fields stay empty and show Saved - leave empty to keep it. Type a new value only to change it. Tick Remove the saved client ID and client secret and click Save to delete them. When nothing is saved, the section shows No credentials saved. When you change the credentials or the locker selection, the cached locker lists and the last API error are cleared.

Availability

Geo zone: offer the method only for addresses in this geo zone. All zones (default) means every Spanish address. Geo zones are managed in System > Localisation > Geo Zones.

Ignore geo zone: offer CityPaq for every Spanish address, even if it is not in the geo zone above.

Advanced

Debug log: writes debug lines to storage/logs/vfd_cpq_debug.log.php (on OpenCart 4 system/storage/logs/vfd_cpq_debug.log.php). The file cannot be read from the web. Correos API errors are always written, even when this is off. Credentials and personal data are never logged.

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, cached lists and logs. Lockers saved in orders are kept. When off (default), everything is kept for a re-install.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API client ID and secret are not included.

Import: paste settings JSON exported from this extension and click Import. The values are checked like a normal save. Saved credentials are kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the CityPaq price. If a Geo zone is set (and Ignore geo zone is off) and the address is outside it, CityPaq is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The extension checks that the delivery address is in Spain, the cart weight and the minimum order amount, finds the price row for Spain (or the * row) and the parcel size, and returns the price. If free shipping applies, the price is 0. The price is calculated in your store default currency, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax class. No request goes to Correos for the price.

The CityPaq locker box appears under the CityPaq method at the delivery method step. The choice is saved as soon as the customer makes it. A locker that is not acceptable is refused with a message, and the previous choice stays. With the Correos list, a locker code is accepted only if Correos offered it for the searched postal code, and its name and address are taken from Correos. A customer can search up to 30 different postal codes per checkout session. After that the customer sees Too many searches. Please enter the CityPaq locker you found on the Correos map.

The Continue button of the delivery method step does not go on with CityPaq without a valid locker. This is checked on the server. The customer sees, for example, Please choose the CityPaq locker where you want to collect your parcel. When the order is placed, the locker is saved in the order.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks CityPaq in the window Shipping method options. The CityPaq locker box appears in that window under the CityPaq option and works as described above. The Continue button of the window does not go on with CityPaq without a valid locker. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the locker of the order is updated with it.

The Correos list is requested only when CityPaq is the selected method, not while the step is drawn. A list is cached for 12 hours per postal code. A failed request is cached for 10 minutes, so the checkout does not wait for Correos on every refresh. The customer never sees the technical error, only the message The Correos CityPaq list cannot be loaded right now. and the manual field.

The extension does not get live rates from Correos, show a map, pre-register shipments, print labels, request pickups or track parcels. Create the shipment in your Correos account using the locker saved in the order.

Pickup points

The chosen locker is added to the shipping method of the order, for example Correos CityPaq - CityPaq locker: .... So the customer sees it in the order history of their account and in the order e-mails, and it is printed on the invoice and shown in Sales > Orders. The OpenCart order success page does not show the shipping method.

On the admin order page, the CityPaq locker panel above the history shows the locker and its Locker code: when it was chosen from a list. To change it, use the Change CityPaq locker field and click Save: with your list, choose another locker from the drop-down; with the Correos list, type a locker code (it is looked up at Correos) or an address; otherwise type a new code or address. Leave the field empty, or keep -- Keep the current locker --, to keep the current locker. Each change also updates the shipping method text of the order and adds an order history entry CityPaq locker changed to: ... without notifying the customer. Changing the locker needs the modify permission for orders (sale/order). Access to the extension settings is not needed. The panel is shown for CityPaq orders also while the extension is disabled.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Correos CityPaq is the first block on Extensions > Extensions > Shipping > VibeFox Correos CityPaq > 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-correos-citypaq 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, Correos CityPaq 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

Correos CityPaq does not appear at checkout: check that the license is active, Enable/Disable is on and the delivery address is in Spain. Check Geo zone (or turn on Ignore geo zone). Check that the price table has a row for Spain or a * row, that the cart is within the weight limits and Minimum order amount, and that the products have Requires Shipping set to Yes.

Customers must type the locker although the Correos list is selected: check that API client ID and API client secret are saved and look at the warning at the top of the settings page. It shows the last Correos API error. HTTP 401/403 means Correos refused the credentials: check them and that your application has access to the "terminals" API. After an error, the next attempt is made after 10 minutes.

No lockers for a postal code: Correos found no active locker for that postal code, its area or its province. The customer can search another postal code or enter the locker found on the Correos CityPaq map.

The drop-down of my lockers does not appear: My lockers is empty or its lines are invalid. Each line needs at least CODE | Name.

Where customers find the locker code: on the Correos CityPaq map linked under the locker field.

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

For developers: the locker of a checkout session and of an order is stored in the table vfd_cpq_locker (with your database prefix). The Correos API address can be replaced with the setting vfd_cpq_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 Correos CityPaq. 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 Correos locker lists and the last API error are always removed. If Remove data on uninstall is on, the settings, the log and lockers of checkout sessions without an order are removed as well. If it is off, the other settings are kept and are used again when you install the extension again. Lockers saved in orders are never deleted, and 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 Correos CityPaq in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Correos and CityPaq are trademarks of their respective owners. This extension is not affiliated with or endorsed by Correos.