VibeFox Correos CityPaq 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, with the cURL and JSON extensions.

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 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-correos-citypaq-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/CorreosCitypaqShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_CorreosCitypaqShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy (the module has its own checkout scripts and styles), then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox Correos CityPaq. 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. Fill in the price table, choose how the customer selects the locker (see Configuration), set Enable Correos CityPaq shipping to Yes and click Save Config.

The module adds the Correos CityPaq shipping method to Magento. Customers see it as Correos CityPaq - Smart parcel locker (method title and method name). It is off after installation (Enable Correos CityPaq shipping = No), and Ship to Specific Countries is set to Spain. The module also creates the table vfd_cpq_locker for the lockers of carts and orders.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Correos CityPaq, 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. Prices and 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; a 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 weight or an amount that is not a number of 0 or more; a Min weight (kg) greater than the Max weight (kg). Invalid prices in the price table and invalid or duplicated lines in My lockers are reported as warnings, and the rest is saved.

Warnings at the top of the group tell you when the price table has no row for Spain and no default row (the method is then not shown), when the chosen locker selection cannot work (no lockers in your list, no API credentials) and what the last Correos API error was. They use the settings of the scope you are editing.

General

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

Enable Correos CityPaq shipping: shows or hides Correos CityPaq at checkout. Default: No.

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

Method name: shown after the method title, as "Method title - Method name". Default: Smart parcel locker. At most 64 characters. An empty field saves the default.

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

Tax on shipping is not set in the module. If your store charges tax on shipping, set the tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.

Prices

Correos does not publish a rate API for CityPaq, so the price comes from this table. Enter your Correos contract prices in the base currency of your store, 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 Delete 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.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). Magento products have no standard dimensions, so the parcel size is found by weight only.

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 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

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

Free shipping from: the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) from which this method costs 0. Used only when Free shipping is Yes.

CityPaq locker selection

The customer must choose the CityPaq locker before placing the order. The section comment has a link to the official Correos CityPaq finder.

Locker selection: how the customer chooses the locker. Default: the customer enters the locker.

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, for example S0000213D | CityPaq Name | Street 1 | 46001 | Valencia. The code and the name are required. Lines without them are dropped with a warning. 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 comment 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.

Magento stores both values encrypted and shows only a mask after saving. Leave the mask as it is to keep a saved value, type a new value to change it. To delete the saved credentials, clear API client ID and click Save Config: the client secret is deleted with it. When you change the credentials or the locker selection, the cached locker lists and the last API error are cleared.

Availability

Ship to Applicable Countries: All Allowed Countries or Specific Countries. Default: Specific Countries.

Ship to Specific Countries: the destination countries for Specific Countries. Default: Spain. Keep Spain in the list: the method is never offered for other countries, even if they are selected here.

Advanced

Debug log: writes debug lines to var/log/vfd_cpq_debug.log.php in the Magento 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 Yes, uninstalling the module with its data deletes the settings, the log and the lockers of carts that never became an order (see Uninstall). The license key, the cached Correos lists and the last API error are always removed. Lockers saved in orders are never deleted.

How it works at checkout

At the shipping step Magento asks the module for the CityPaq price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module checks that the delivery address is in Spain, the cart weight and 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. A Magento cart price rule with free shipping also makes the price 0. The price is in your base currency; Magento shows it in the customer's currency and adds tax on shipping if your store charges it. No request goes to Correos for the price.

When the customer selects Correos CityPaq, the CityPaq locker box appears under the shipping methods. With the Correos list it has a Postal code field and a Search button (Enter works too), and the postal code of the delivery address is searched automatically the first time. With your list it has the drop-down -- Select a CityPaq locker --. For manual entry it has the field CityPaq locker code or address and the link Find a CityPaq locker on the Correos map, which opens the Correos finder in Spanish when the locale of the store view is Spanish and in English otherwise.

The choice is saved with the cart as soon as the customer makes it, so a page refresh does not lose 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 new search drops a chosen locker that is not in the new list. 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.

Next in the shipping step does not go on without a valid locker. Magento checks this again on the server. The customer sees, for example, Please choose the CityPaq locker where you want to collect your parcel. and the checkout stays on the shipping step.

The Correos list is requested only when the customer selects CityPaq, not for every visitor of the checkout. 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 is made for the standard Magento checkout (Luma and Blank themes). Third-party checkouts, such as Hyvä or one-step checkouts, need their own integration.

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

When the order is placed, the chosen locker is saved with the order and added to its shipping description, for example Correos CityPaq - Smart parcel locker - CityPaq locker: followed by the locker. The customer sees this text in the order e-mails, in the order in their account and on invoices.

On the admin order page (Sales > Orders > View, Information tab) the block CityPaq locker shows the locker and its Locker code when it was chosen from a list, or Entered by the customer. Without a locker it shows No CityPaq locker was selected for this order. The block is also shown for older orders and when the module is switched off.

To change the locker, click Change CityPaq locker, enter the new locker 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. The locker and the shipping description of the order are updated, the page shows The CityPaq locker of the order was updated., and an order comment CityPaq locker changed to: ... is added without notifying the customer. An empty field changes nothing. Changing the locker needs an Admin role that allows editing orders (Sales > Operations > Orders > Actions > Edit). Access to the configuration is not needed.

An order placed without a locker while a locker is asked, for example an order created in the Admin, has no locker; the debug log shows an error for it. Set the locker on the order page with Change CityPaq locker.

License key

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

Correos CityPaq does not appear at checkout: check that the license is active and Enable Correos CityPaq shipping is Yes for the website of the store, and that the delivery address is in Spain. Check that Spain is allowed by Ship to Applicable Countries and Ship to Specific Countries, 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.

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 warnings at the top of the group. They show 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 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.

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

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_CorreosCitypaqShipping. It removes the data and the code.

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

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 Yes, the settings, the log and the lockers of carts without an order are removed too. If it is No, the settings are kept for a re-install. The table vfd_cpq_locker and the lockers saved in orders are never deleted, and the shipping descriptions of orders keep the locker.

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