VibeFox Correos CityPaq for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

Доставка в Испанию: постаматы CityPaq есть только в Испании, поэтому перевозчик предлагается только для адресов доставки в Испании.

Учётные данные API Correos (только для актуального списка постаматов): список постаматов CityPaq Correos получает активные постаматы из API Correos «terminals». На портале разработчиков Correos откройте API «terminals» и нажмите Request access для вашего приложения. Correos одобряет запросы своих деловых клиентов и присылает client ID и client secret. Они также отображаются в разделе My applications на портале. Если покупатели вводят постамат сами или выбирают из вашего списка, учётные данные API не нужны.

Лицензионный ключ VibeFox: покупается на vibefox.net. Один ключ работает на одном домене.

Установка

1. В back office перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По окончании загрузки нажмите Configure или позже найдите VibeFox Correos CityPaq в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы Configure и нажмите Activate (см. раздел «Лицензионный ключ»).

4. Заполните таблицу цен, выберите, как покупатель выбирает постамат (см. Настройки), и нажмите Save.

При установке модуль создаёт перевозчика Correos CityPaq с текстом срока доставки Delivery to a Correos CityPaq parcel locker. Перевозчик назначается всем группам клиентов и зоне Испании. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Не задавайте там цены: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Correos CityPaq > Configure. Каждый раздел имеет свою кнопку Save, которая сохраняет всю страницу. Цены и суммы принимают десятичную запятую или десятичную точку.

Предупреждения над настройками сообщают, когда перевозчик не найден, когда в таблице цен нет строки для Испании и строки по умолчанию, когда выбранный способ выбора постамата не может работать (нет постаматов в вашем списке, нет учётных данных API), какая была последняя ошибка API Correos, а также когда модуль не знает единицу веса вашего магазина (тогда вес товаров читается как кг; задайте kg, g, lb или oz в International > Localization). Если название пустое, некорректное или длиннее 64 символов, если вес или сумма не является допустимым числом не меньше 0 или если Min weight (kg) больше Max weight (kg), страница показывает ошибку и ничего не сохраняется. Некорректные цены в таблице цен и некорректные или повторяющиеся строки в My lockers выводятся как предупреждения, остальное сохраняется.

Общие

Постаматы CityPaq есть только в Испании, поэтому перевозчик никогда не предлагается для других стран.

Enable/Disable: включает или выключает доставку Correos CityPaq. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

Name: название способа доставки, которое видит покупатель при оформлении заказа. Оно же является названием перевозчика. По умолчанию: Correos CityPaq. Обязательно, не более 64 символов.

Tax: налоговое правило перевозчика. PrestaShop добавляет этот налог к ценам из таблицы. No tax означает, что цены окончательные.

Цены (в заголовке раздела указана валюта магазина по умолчанию)

Correos не публикует API тарифов для CityPaq, поэтому цена берётся из этой таблицы. Введите тарифы по вашему договору с Correos в валюте магазина по умолчанию без налогов.

Price table: строка для Spain (ES) и/или строка по умолчанию * Default. Каждая строка содержит базовую Price и необязательные цены для размеров посылок XS (до 1 кг), S (до 2 кг), M (до 3 кг), L (до 5 кг) и XL (больше 5 кг). Цена размера 0 или пустая использует базовую цену. Нажмите + Add row, чтобы добавить строку, и значок корзины, чтобы удалить её. Без подходящей строки перевозчик скрывается. Если страна указана дважды, используется только первая строка.

Calculation type: как определяется размер посылки.

Веса товаров переводятся в кг из единицы веса вашего магазина (например, kg, g, lb или oz).

Условия

Min weight (kg): скрывает перевозчика, если корзина легче. 0 означает без ограничения.

Max weight (kg): скрывает перевозчика, если корзина тяжелее. По умолчанию: 30, потому что CityPaq принимает посылки до 30 кг. 0 означает без ограничения.

Minimum order amount: показывать перевозчика только тогда, когда промежуточная сумма корзины (товары, требующие доставки, после скидок, до налогов) достигает этой суммы. Оставьте пустым, чтобы показывать всегда.

Бесплатная доставка

Free shipping: включает бесплатную доставку CityPaq от суммы, указанной ниже.

Free shipping from: промежуточная сумма корзины (после скидок, до налогов), начиная с которой этот перевозчик стоит 0. Используется только когда включена опция Free shipping.

Выбор постамата CityPaq

Раздел содержит ссылку на официальный поиск постаматов CityPaq на сайте Correos.

Locker selection: как покупатель выбирает постамат перед оформлением заказа. По умолчанию: покупатель вводит постамат.

Если вы выбираете список Correos без учётных данных API или свой список, когда My lockers пуст, покупателей просят ввести постамат вручную.

My lockers: используется, когда Locker selection установлен на ваш список. Один постамат на строку: CODE | Name | Address | Postal code | City. Код и название обязательны. Если код указан дважды, используется только первая строка.

Список Correos CityPaq (API) (используется только со списком Correos CityPaq)

Раздел содержит ссылку на страницу API «terminals» на портале разработчиков Correos. Читается только список постаматов. Цены всегда берутся из таблицы цен.

API client ID: client_id вашего приложения на портале разработчиков Correos.

API client secret: client_secret вашего приложения на портале разработчиков Correos.

После сохранения оба поля остаются пустыми и показывают Saved - leave empty to keep it. Введите новое значение, только если хотите его изменить. Отметьте Remove the saved client ID and client secret и нажмите Save, чтобы удалить их. Если ничего не сохранено, раздел показывает No credentials saved. При изменении учётных данных или выбора постамата кэшированные списки постаматов очищаются.

Доступность без зон доставки

Ignore shipping zones: предлагать CityPaq для любого испанского адреса, даже если зона адреса не связана с перевозчиком. Когда опция включена, перевозчик привязывается ко всем активным зонам, включая зоны, созданные позже. Когда вы снова её выключаете, перевозчик получает обратно зоны, которые у него были раньше. Выключено (рекомендуется) означает, что используются зоны, заданные в Shipping > Carriers.

Дополнительно

Debug log: пишет строки отладки в logs/vfd_cpq_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ошибки API Correos записываются всегда, даже когда опция выключена. Учётные данные и персональные данные никогда не записываются в журнал.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Remove data on uninstall: когда опция включена, удаление модуля удаляет настройки, перевозчика, кэшированные списки и журналы. Постаматы, сохранённые в заказах, остаются. Когда опция выключена, всё сохраняется для повторной установки.

Как это работает при оформлении заказа

На этапе доставки PrestaShop запрашивает у модуля цену CityPaq. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму заказа. Модуль проверяет, что адрес доставки находится в Испании, вес корзины и минимальную сумму заказа, находит строку цен для Испании (или строку *) и размер посылки и возвращает цену. Если применяется бесплатная доставка, цена равна 0. Цена рассчитывается в валюте магазина по умолчанию и затем показывается в валюте корзины покупателя. Налог добавляется по налоговому правилу перевозчика.

Когда покупатель выбирает CityPaq, под перевозчиком появляется блок CityPaq locker. Выбор сохраняется в корзине сразу после того, как покупатель его сделал. Недопустимый постамат отклоняется с сообщением, и предыдущий выбор сохраняется. При списке Correos код постамата принимается, только если Correos предложил его для искомого почтового индекса, а название и адрес берутся из Correos. Покупатель может искать до 30 разных почтовых индексов на одну корзину. После этого он видит Слишком много поисков. Введите постамат CityPaq, который вы нашли на карте Correos.

Кнопка Continue на этапе доставки не продолжает без действительного постамата. Это также проверяется на сервере. Покупатель видит, например, Выберите постамат CityPaq, в котором хотите получить посылку. При оформлении заказа постамат из корзины сохраняется в заказе.

Список Correos запрашивается, только когда покупатель выбирает CityPaq, а не для каждого посетителя этапа доставки. Список кэшируется на 12 часов для каждого почтового индекса. Неудачный запрос кэшируется на 10 минут, чтобы оформление заказа не ждало Correos при каждом обновлении. Тайм-аут API — 12 секунд. Покупатель никогда не видит техническую ошибку, только короткое сообщение и поле ручного ввода. Блок постамата работает с темами Classic и Hummingbird.

Модуль не получает актуальные тарифы от Correos, не показывает карту, не регистрирует отправления заранее, не печатает этикетки, не заказывает забор посылок и не отслеживает посылки. Создайте отправление в вашем аккаунте Correos, используя постамат, сохранённый в заказе.

Пункты выдачи

Выбранный постамат сохраняется в заказе. Покупатель видит его как CityPaq locker: на странице подтверждения заказа и на странице сведений о заказе в личном кабинете. В письме с подтверждением заказа и в письме о новом заказе модуля Mail alerts постамат добавляется к строке перевозчика, например, Correos CityPaq - CityPaq locker: ....

На странице заказа в админке блок CityPaq locker показывает постамат и его Locker code:, если он был выбран из списка. Чтобы изменить его, используйте поле Change CityPaq locker и нажмите Save: при вашем списке выберите другой постамат из выпадающего списка; при списке Correos введите код постамата (он проверяется в Correos) или адрес; в остальных случаях введите новый код или адрес. Оставьте поле пустым, чтобы сохранить текущий постамат. Каждое изменение добавляет закрытое сообщение к заказу: Постамат CityPaq изменён на: .... Для изменения постамата нужно право редактировать заказы. Доступ к страницам Modules не нужен.

Лицензионный ключ

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Correos CityPaq — это первый блок на странице Modules > Module Manager > VibeFox Correos CityPaq > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-correos-citypaq и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку back office (включены английский и русский).

Если ключ не принят, блок сообщает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или освобождения слота домена в аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своём аккаунте на vibefox.net.

Без активного ключа перевозчик Correos CityPaq не показывается покупателям при оформлении заказа, и тариф не рассчитывается. Витрина PrestaShop не знает, что вы вошли в back office, поэтому перевозчик скрыт и для вас: модуль можно настроить до покупки ключа, но нельзя проверить при оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова, пока вы работаете в back office: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

Correos CityPaq не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и адрес доставки находится в Испании. В Shipping > Carriers проверьте, что перевозчик охватывает зону Испании и группу покупателя (или включите Ignore shipping zones). Проверьте, что в таблице цен есть строка для Испании или строка *, и что корзина укладывается в ограничения по весу и Minimum order amount. Товары также могут быть ограничены определёнными перевозчиками на странице товара.

Покупатели должны вводить постамат вручную, хотя выбран список Correos: проверьте, что API client ID и API client secret сохранены, и посмотрите предупреждение над настройками. Оно показывает последнюю ошибку API Correos. HTTP 401/403 означает, что Correos отклонил учётные данные: проверьте их и то, что ваше приложение имеет доступ к API «terminals». После ошибки следующая попытка выполняется через 10 минут.

Нет постаматов для почтового индекса: Correos не нашёл активных постаматов для этого индекса, его района или провинции. Покупатель может искать другой индекс или ввести постамат, найденный в поиске CityPaq на сайте Correos.

Выпадающий список моих постаматов не появляется: My lockers пуст или его строки некорректны. Каждая строка должна содержать как минимум CODE | Name.

Где покупатели находят код постамата: в поиске CityPaq на сайте Correos, ссылка на который находится под полем постамата.

Страница сообщает, что перевозчик не найден или не удалось обновить перевозчика: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его снова. Сброс сохраняет настройки и статус перевозчика.

Заметки для разработчиков: постамат корзины и заказа хранится в таблице vfd_cpq_locker (с префиксом вашей базы данных). Модуль использует рабочий API Correos «terminals».

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Correos CityPaq и выберите Uninstall. Лицензионный ключ, статус лицензии, кэшированные списки постаматов Correos и последняя ошибка API всегда удаляются. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют свою историю), а настройки, журнал и постаматы корзин без заказа удаляются. Если выключено, перевозчик только отключается и все настройки сохраняются. Повторная установка модуля восстанавливает статус перевозчика, который был раньше. Постаматы, сохранённые в заказах, никогда не удаляются.

Correos и CityPaq — товарные знаки их владельцев. Этот модуль не аффилирован с Correos и не одобрен Correos.