VibeFox Correos CityPaq for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

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

Delivery to Spain: CityPaq lockers exist only in Spain, so the carrier 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

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 Correos CityPaq 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. Fill in the price table, choose how the customer selects the locker (see Configuration) and click Save.

On install the module creates the Correos CityPaq carrier with the delivery time text Delivery to a Correos CityPaq parcel locker. The carrier is assigned to all customer groups and to the zone of Spain. 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 Correos CityPaq > Configure. Each section has its own Save button, which saves the whole page. Prices and amounts accept a decimal comma or a decimal point.

Warnings above the settings tell you when the carrier was not found, 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 your shop weight unit is not known to the module (product weights are then read as kg; set kg, g, lb or oz in International > Localization). 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, or Min weight (kg) is greater than Max weight (kg), the page shows an error and nothing is saved. Invalid prices in the price table 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 carrier is never offered for other countries.

Enable/Disable: turns Correos CityPaq shipping on or off. This is the same switch as the carrier status in Shipping > Carriers.

Name: the shipping method name shown to the customer at checkout. It is also the carrier name. Default: Correos CityPaq. Required, at most 64 characters.

Tax: the tax rule of the carrier. PrestaShop adds this tax on top of the prices from the table. No tax means the prices are final.

Prices (the section title shows your shop 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 shop 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 trash icon to remove one. Without a matching row the carrier 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 your shop weight unit (for example kg, g, lb or oz).

Conditions

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

Max weight (kg): hide the carrier when the cart is heavier. Default: 30, because CityPaq accepts parcels up to 30 kg. 0 means no limit.

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

Free shipping

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

Free shipping from: the cart subtotal (after discounts, before tax) from which this carrier 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). Each locker shows its name, address, postal code, town and opening hours. 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 finder.

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.

My lockers: used when Locker selection is set to your list. One locker per line: CODE | Name | Address | Postal code | City. The code and the name are required. If a code is listed twice, only the first line is used.

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 are cleared.

Availability without shipping zones

Ignore shipping zones: offer CityPaq for every Spanish address, even if the zone of the address is not linked to the carrier. When on, the carrier is linked to every active zone, including zones created later. When you turn it off again, the carrier gets back the zones it had before. Off (recommended) means the zones set in Shipping > Carriers are used.

Advanced

Debug log: writes debug lines to logs/vfd_cpq_debug.log.php in the module folder. The file cannot be opened 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 module deletes the settings, the carrier, cached lists and logs. Lockers saved in orders are kept. When off, everything is kept for a re-install.

How it works at checkout

At the shipping step PrestaShop asks the module for the CityPaq price. Only physical products count: virtual products add no weight and are not included in the order amount. The module 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 shop default currency and then shown in the customer's cart currency. Tax is added by the carrier tax rule.

When the customer selects CityPaq, the CityPaq locker box appears under the carrier. The choice is saved to the cart 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 cart. After that the customer sees Too many searches. Please enter the CityPaq locker you found on the Correos map.

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

The Correos list is requested only when the customer selects CityPaq, not for every visitor of the shipping step. 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 API timeout is 12 seconds. The customer never sees the technical error, only a short message and the manual field. The locker box works with the Classic and Hummingbird themes.

The module 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 saved in the order. The customer sees it as CityPaq locker: on the order confirmation page and on the order details page in the customer account. In the order confirmation e-mail and in the new order e-mail of the Mail alerts module, the locker is added to the carrier line, for example Correos CityPaq - CityPaq locker: ....

On the admin order page, the CityPaq locker block 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 to keep the current locker. Each change adds a private order message CityPaq locker changed to: .... Changing the locker needs permission to edit orders. Access to the Modules pages is not needed.

License key

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

Correos CityPaq does not appear at checkout: check that the license is active, Enable/Disable is on and the delivery address is in Spain. In Shipping > Carriers check that the carrier covers the zone of Spain and the customer's group (or turn on Ignore shipping zones). Check that the price table has a row for Spain or a * row, and that the cart is within the weight limits and Minimum order amount. Products can also be limited to certain carriers in the product page.

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 above the settings. 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 finder.

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 finder linked under the locker field.

The page says the carrier was not found, or the carrier could not be updated: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again. Reset keeps the settings and the carrier status.

Developer notes: the locker of a cart and of an order is stored in the table vfd_cpq_locker (with your database prefix). The module uses the production Correos "terminals" API.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Correos CityPaq and choose Uninstall. The license key, the license status, the cached Correos locker lists and the last API error are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history), and the settings, the log and lockers of carts without an order are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again restores the carrier status it had before. Lockers saved in orders are never deleted.

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