VibeFox Cargoson for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Аккаунт Cargoson (только для тарифов в реальном времени): тарифы в реальном времени используют API расчёта фрахта Cargoson. Запросы тарифов на фрахт требуют подписки Cargoson с доступом к API (план Advanced или выше на момент написания). Ключ API выдаётся в вашем аккаунте Cargoson; если в вашем плане не отображаются настройки API, обратитесь в поддержку Cargoson. Цены поступают от перевозчиков и прайс-листов, подключённых к этому аккаунту. Если вы используете только фиксированные цены, аккаунт Cargoson не нужен.

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

Установка

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

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

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

4. Выберите способ расчёта стоимости доставки и заполните соответствующие разделы: фиксированные цены, а для тарифов в реальном времени — ключ API и почтовый индекс отправки (см. Настройки). Нажмите Save.

При установке модуль создаёт перевозчика Cargoson с текстом срока доставки Delivery by the cheapest Cargoson carrier. Перевозчик назначается всем зонам и всем группам покупателей. Зоны, группы покупателей, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Cargoson > Configure. Они применяются ко всем зонам перевозчика. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. После сохранения вы увидите Settings saved. Cached Cargoson prices were cleared. Десятичные числа можно вводить с точкой или запятой. Ничего не сохраняется, и страница показывает ошибку, если в числовом поле есть текст или отрицательное число, Currency conversion rate равен 0, Minimum weight больше Maximum weight, Method title длиннее 64 символов, Price currency — не трёхбуквенный код валюты, или в строке таблицы цен указан неверный код страны или цена. Если модуль не распознаёт единицу веса магазина, после сохранения появится предупреждение о том, что веса товаров принимаются в килограммах; задайте единицу в International > Localization (Local units).

General

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

Method title: название перевозчика, которое показывается в корзине и при оформлении заказа. По умолчанию: Cargoson. Обязательное поле. Это также название перевозчика в Shipping > Carriers.

Shipping cost: способ расчёта цены.

Причина отсутствия тарифа в реальном времени записывается в журнал модуля. Покупателю она никогда не показывается.

API Cargoson (нужно только для тарифов в реальном времени)

API key: ключ API из вашего аккаунта Cargoson. Он отправляется только в Cargoson и никогда не показывается покупателям и не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Введите новое значение, только если хотите его изменить.

Remove the saved API key: появляется, когда ключ сохранён. Включите опцию и сохраните, чтобы удалить ключ.

Carrier: какие тарифы используются. Покупатель видит одну ставку.

Package type code: код типа упаковки Cargoson, который отправляется с запросом цены. По умолчанию: CLL. Примеры API Cargoson используют EUR (паллета EUR) и FIN (паллета FIN). Для посылок используйте код упаковки вашего аккаунта Cargoson. Заказ отправляется как одна посылка с общим весом корзины.

Price currency: валюта цен в вашем аккаунте Cargoson в виде трёхбуквенного кода. По умолчанию: EUR. API возвращает суммы без кода валюты.

Currency conversion rate: нужен, только если валюта цен отличается от основной валюты магазина: 1 единица валюты Cargoson = X единиц основной валюты магазина. Оставьте поле пустым, чтобы отклонять такие цены, — тогда покупатель никогда не будет оплачивать доставку в неверной валюте.

Отправка из (адрес отправки) (используется для тарифов в реальном времени)

Collection country: страна, из которой вы отправляете. По умолчанию это страна вашего магазина.

Collection postcode: почтовый индекс, из которого вы отправляете. Cargoson его требует. Если поле пустое и страна отправки совпадает со страной магазина, используется почтовый индекс магазина из Shop Parameters > Contact > Stores.

Дата отправки, которая передаётся в Cargoson, — сегодня по часовому поясу магазина или ближайший понедельник, если сегодня выходной.

Фиксированные цены (используются, когда Shipping cost установлен в Fixed prices, а также как запасной вариант для тарифов в реальном времени)

Price per country and size: таблица со столбцом Country (двухбуквенный код), столбцом Price и ценами по весу корзины в основной валюте магазина, без налога: XS до 1 кг, S до 2 кг, M до 3 кг, L до 5 кг, XL свыше 5 кг. Если цена размера пустая или равна 0, используется столбец Price; пустой Price означает, что для этого размера фиксированного тарифа нет. Нажмите Add country, чтобы добавить строку, и значок корзины, чтобы удалить её. Используйте * как код страны для всех стран без собственной строки. Страны без строки (если строки * нет) не получают фиксированного тарифа, поэтому перевозчик для них скрывается. Цены должны быть числами, не меньше 0. Пустая строка игнорируется.

Fixed price applies: Per order взимает цену один раз. Per item (price × quantity) умножает её на количество товаров в корзине. Тарифы Cargoson в реальном времени всегда считаются за отправление.

Условия

Minimum weight: скрывает перевозчика при весе корзины ниже этого значения, в кг. 0 означает без ограничения.

Maximum weight: скрывает перевозчика при весе корзины выше этого значения, в кг. По умолчанию: 25. 0 означает без ограничения.

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

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

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

Tax: налоговое правило перевозчика или No tax. Тарифы перевозчиков в Cargoson обычно указываются без НДС. Выберите No tax, если ваши цены уже включают налог.

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

Обычно перевозчик предлагается в зонах, назначенных ему в Shipping > Carriers.

Ignore shipping zones: предлагает Cargoson для указанных ниже стран независимо от зон, назначенных перевозчику. Если включить опцию и сохранить, перевозчик назначается всем зонам; зоны, созданные позже, тоже назначаются. Если выключить опцию и сохранить, перевозчик возвращает свои прежние зоны.

Countries: страны назначения для этого режима. Оставьте поле пустым, чтобы использовать все страны, в которые вы доставляете (активные страны). Это поле используется, только если включена опция Ignore shipping zones.

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

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

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену Cargoson. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму заказа. Веса товаров переводятся из единицы измерения магазина в килограммы. Модуль сначала проверяет условия: страна доставки, вес корзины и минимальная сумма заказа. Если действует бесплатная доставка, цена равна 0 и запрос в Cargoson не отправляется.

В режиме фиксированных цен цена берётся из таблицы. В режимах тарифов в реальном времени модуль отправляет в Cargoson дату отправки, страну и почтовый индекс отправки, страну и почтовый индекс доставки, а также одну посылку с кодом типа упаковки и общим весом корзины (не менее 0,1 кг). Тариф в реальном времени запрашивается, только если в адресе доставки указан почтовый индекс. Cargoson возвращает цены ваших перевозчиков; модуль выбирает самую низкую (среди выбранного перевозчика, если он задан) и при необходимости пересчитывает её в основную валюту магазина. Цена рассчитывается в основной валюте магазина и затем показывается в валюте корзины покупателя.

Каждый ответ кэшируется на 1 час, поэтому одна и та же корзина не вызывает новый запрос. Неудачный запрос кэшируется на 10 минут, чтобы оформление заказа не ждало Cargoson при каждом обновлении. Тайм-аут API составляет 10 секунд. Если Cargoson возвращает ошибку, не возвращает цену для маршрута или возвращает цену в другой валюте без курса пересчёта, покупатель не видит ошибки. Перевозчик скрывается или, в запасном режиме, используется фиксированная цена.

Если вы редактируете перевозчика в Shipping > Carriers после того, как по нему есть заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически переходит на новую версию.

Модуль только рассчитывает тарифы. Он не создаёт отправления или заявки в Cargoson, не печатает этикетки и не отслеживает посылки, а покупатели не могут выбрать постамат или пункт выдачи. Корзина рассчитывается как одна посылка с общим весом; габариты посылки не передаются. Показывается только самая низкая цена, а не список перевозчиков.

Заказы

На странице заказа Cargoson отображается блок Cargoson shipping с тарифом, рассчитанным при оформлении:

Carrier, Service и Cargoson service ID: рассчитанные перевозчик и услуга Cargoson, показываются, если использовался тариф в реальном времени.

Price source: Cargoson live price, Fixed price или Free shipping threshold.

Calculated price (excl. tax): цена в основной валюте магазина.

Расчёт сохраняется при оформлении заказа и потом не меняется. Бронируйте отправление в Cargoson или через собственные интеграции Cargoson.

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

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

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

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

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

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

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

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

Тарифы в реальном времени не появляются: посмотрите поле Log на странице модуля. Ошибки API всегда записываются в журнал; включите Debug log, чтобы видеть каждый расчёт. Типичные причины: не введён почтовый индекс доставки, нет почтового индекса отправки, ключ API отклонён (неверный или просроченный ключ либо нет доступа к API в вашем тарифе Cargoson), нет перевозчика для маршрута или веса, либо цена в другой валюте. При Cargoson live prices, fixed prices if the API fails покупатели по-прежнему видят фиксированную цену, пока вы устраняете проблему.

Cargoson отклоняет тип упаковки: используйте код упаковки, который ваш аккаунт Cargoson применяет в Package type code. Причина указана в журнале.

Цена в другой валюте отклоняется: установите Price currency в валюту ваших тарифов Cargoson и введите Currency conversion rate.

Налог на доставку взимается дважды: ваши тарифы Cargoson уже включают НДС. Установите Tax в значение No tax.

Тарифы кажутся устаревшими после изменения: нажмите Save на странице модуля. Это очистит кэшированные тарифы Cargoson.

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

Удаление

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

Cargoson — товарный знак его правообладателя. Этот модуль не связан с Cargoson и не одобрен Cargoson.