VibeFox Blue Express for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

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

Учётная запись Blue Express (только для тарифов в реальном времени): тарифы в реальном времени требуют учётной записи e-commerce Blue Express и её API-ключа (x-api-key). Запросите его у Blue Express: developers.bluex.cl или gpo.integraciones@bx.cl. Используемая вами услуга (EX, PY или MD) должна быть подключена в вашем договоре с Blue Express. Если вы используете только фиксированные цены, API-ключ не нужен.

Регионы Чили: для тарифа в реальном времени в адресе доставки должен быть указан чилийский регион. Если в вашем магазине нет регионов для Чили, модуль может добавить их за вас (см. Настройки).

Пункты выдачи: карта Blue Express загружается с widget-pudo.blue.cl в браузере покупателя.

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

Установка

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

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

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

4. Введите API-ключ, услугу, код района отправления (например SCL), курс CLP, если валюта вашего магазина не CLP, и фиксированные цены (например CL=4500). Включите Pickup point carrier, если хотите предлагать самовывоз из пунктов Blue Express. Нажмите Save. См. Настройки.

При установке модуль создаёт двух перевозчиков: Blue Express (доставка на дом, текст срока доставки Home delivery, включён) и Blue Express pickup point (текст срока доставки Pickup at a Blue Express point, выключен, пока вы его не включите). Оба назначены зоне Чили и всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения размеров можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Blue Express > Configure. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш тарифов Blue Express и данных о коммунах. В верхней части страницы отображаются предупреждения о настройках, которые скрыли бы перевозчиков или тариф в реальном времени: нет API-ключа, валюта магазина не CLP без курса обмена, пустая таблица фиксированных цен, нет регионов для Чили, единица веса или размеров магазина, которую модуль не распознаёт (тогда веса читаются как кг, а размеры как см), или удалённый перевозчик. Некорректные значения отклоняются с ошибкой, и ничего не сохраняется: пустое или некорректное название перевозчика, название длиннее 64 символов, отрицательное или некорректное число либо Min weight (kg) больше Max weight (kg). Условия и цены ниже применяются к обоим перевозчикам.

Общие

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

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

Tax status: None (no tax on shipping) или Taxable с одним из ваших налоговых правил. Цены Blue Express включают IVA. Выберите None, если PrestaShop не должен добавлять налог сверху. Применяется к обоим перевозчикам.

Самовывоз из пунктов Blue Express (PUDO)

Pickup point carrier: предлагает доставку в пункт Blue Express, выбранный покупателем, как второго перевозчика наряду с доставкой на дом. По умолчанию выключено. Это тот же переключатель, что и статус перевозчика Blue Express pickup point в Shipping > Carriers.

Pickup point name: название перевозчика, которое отображается при оформлении заказа для самовывоза из пункта Blue Express. По умолчанию: Blue Express pickup point. Обязательное поле, не более 64 символов.

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

API key: ваш API-ключ Blue Express (заголовок x-api-key). Без него используются только фиксированные цены. После сохранения поле остаётся пустым и показывает A key is saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить. Отметьте Remove the saved API key и сохраните, чтобы удалить ключ.

Service: услуга Blue Express для расчёта тарифа: Express (EX) (по умолчанию), Prioritario (PY) или SameDay (MD). Она должна быть подключена в вашем договоре с Blue Express.

Origin district code: код района Blue Express для места, откуда вы отправляете, например SCL для Сантьяго (по умолчанию). Если не уверены, уточните у Blue Express.

CLP per 1 unit of store currency: если валюта магазина по умолчанию не CLP, подпись показывает её, например CLP per 1 EUR. Цены Blue Express указаны в чилийских песо (CLP). Введите, сколько CLP стоит одна единица валюты магазина по умолчанию, например 1050. Без этого значения тарифы в реальном времени не используются. Игнорируется, если валюта магазина — CLP.

Цена

Rate source: способ расчёта цены. Тариф в реальном времени требует чилийский адрес с регионом и коммуной (городом). Ошибки записываются в журнал и никогда не показываются покупателю.

Fixed prices: одна строка на страну в формате COUNTRY_CODE=PRICE, в валюте магазина по умолчанию, без налогов, например CL=4500 в магазине с CLP или CL=4.50 в магазине с EUR. В качестве десятичного разделителя принимаются запятая и точка. Некорректные строки игнорируются и перечисляются в предупреждении при сохранении. Для страны без строки фиксированной цены нет, поэтому перевозчики для неё скрываются, когда нужна фиксированная цена. Фиксированные цены можно использовать для любой страны.

Fixed price per: Order взимает цену один раз. Item (price x quantity) умножает её на количество товаров в корзине. Это относится только к фиксированной цене. Тариф API всегда рассчитан на всё отправление.

Условия

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

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

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

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

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

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

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

Ignore shipping zones: предлагает обоих перевозчиков во всех зонах. Страны тогда ограничиваются списком ниже. Зоны, созданные позже, также добавляются. Когда вы выключаете эту опцию, перевозчики возвращаются к зонам, которые у них были раньше.

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

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

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

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

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

Регионы Чили (показывается, только если в вашем магазине нет пригодных регионов для Чили)

Blue Express требует регион чилийского адреса (RM, VS и т. д.) для тарифа в реальном времени. PrestaShop по умолчанию не включает регионы Чили. Нажмите Add Chilean regions, чтобы добавить 16 регионов Чили как штаты Чили с кодами, которые использует Blue Express, и показать поле региона в форме чилийского адреса. Регионы, которые у вас уже есть (по коду или по названию), не добавляются повторно. Ничего не меняется, пока вы не нажмёте кнопку. Вы также можете добавить их сами в International > Locations > States с кодами RM, VS и т. д.

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

На шаге доставки PrestaShop запрашивает у модуля цену каждого перевозчика Blue Express. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в промежуточную сумму. Модуль проверяет Countries (с Ignore shipping zones), вес корзины и Minimum order subtotal. Если применяется бесплатная доставка, цена равна 0 и запрос в Blue Express не отправляется.

Для тарифа в реальном времени адрес должен быть в Чили, с регионом и городом (коммуной). Модуль сначала просит Blue Express распознать коммуну, затем запрашивает цену для услуги, района отправления, назначения и посылок. Каждый товар отправляется с весом и размерами, переведёнными в кг и см. Товары без веса или размера отправляются как 0,01 кг, 10 x 10 x 10 см. Объявленная стоимость отправляется в CLP. Цена в CLP пересчитывается в валюту магазина по умолчанию и затем показывается в валюте корзины покупателя.

Тарифы кэшируются на 1 час, данные о коммунах — на 12 часов. Неудачный вызов API запоминается на 5 минут, а тайм-аут составляет 10 секунд, чтобы медленный или недоступный API не замедлял каждое обновление оформления заказа. Ошибки API никогда не показываются покупателю: перевозчик скрывается или, в режиме запасной фиксированной цены, используется фиксированная цена. Причина записывается в журнал.

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

Модуль не создаёт отправления и этикетки в Blue Express, не присваивает номера отслеживания и не показывает обновления статуса. Создайте отправление в своей учётной записи Blue Express. Региональных тарифных таблиц по коммунам нет: используйте тариф API Blue Express или одну фиксированную цену за страну. Тарифы в реальном времени работают только для Чили.

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

Когда покупатель выбирает Blue Express pickup point на шаге доставки, под ним появляется блок с кнопкой Choose pickup point. Кнопка открывает официальную карту Blue Express, где покупатель выбирает пункт. Выбранный пункт отображается с названием и адресом, а кнопка меняется на Change pickup point. Пункт сохраняется в корзине, и тариф пересчитывается по цене самовывоза Blue Express (PUDO). Если цена меняется, страница перезагружается, чтобы её показать. Пока пункт не выбран, перевозчик показывает цену доставки посылки на дом.

Покупатель не может продолжить без пункта: Please choose a Blue Express pickup point. Магазин проверяет это, когда покупатель нажимает Continue на шаге доставки. Некорректный код пункта отклоняется сообщением The selected Blue Express pickup point is not valid. Please choose it again on the map., и предыдущий выбор сохраняется.

При оформлении заказа пункт сохраняется в заказе вместе с кодом агентства Blue Express, названием и адресом. На странице заказа в панели администратора он показывается в блоке Blue Express pickup point. Нажмите Edit, чтобы выбрать другой пункт кнопкой Choose on the Blue Express map или ввести Agency code, Name и Address вручную, затем нажмите Save pickup point. Изменение записывается как приватное сообщение к заказу. Для смены пункта нужны только права на редактирование заказов, а не доступ к страницам Modules. Покупатель видит пункт на странице подтверждения заказа, на странице сведений о заказе и в письме с подтверждением заказа — рядом с названием перевозчика. Новое письмо о заказе для магазина (из модуля Mail alerts) также показывает код агентства. Существующие заказы сохраняют свои данные о пункте выдачи.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Blue Express находится первым на странице Modules > Module Manager > VibeFox Blue Express > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой лицензия действительна, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-blue-express и ссылка 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.

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

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

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

Blue Express не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable/Disable (или Pickup point carrier). В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя, или включите Ignore shipping zones и проверьте Countries. Прочитайте предупреждения в верхней части страницы модуля. Проверьте ограничения по весу, Minimum order subtotal и наличие строки для страны в Fixed prices, если вы используете фиксированные цены или запасной вариант. Товары также могут быть ограничены определёнными перевозчиками на странице товара.

Тарифы в реальном времени не появляются: при Blue Express API only перевозчики скрываются, когда тарифа нет. Включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице модуля. Типичные причины: нет API-ключа, валюта магазина не CLP без курса обмена, в адресе нет региона или коммуны, коммуна не распознана Blue Express или ошибка API (например HTTP 401 или 403, когда API-ключ отклонён). При Blue Express API, fixed price if the API gives no rate покупатели по-прежнему получают фиксированную цену, пока вы исправляете проблему.

У чилийских адресов нет региона: страница показывает предупреждение об отсутствующих регионах. Нажмите Add Chilean regions на странице модуля. Покупателям, чьи адреса сохранены без региона, нужно отредактировать адрес и выбрать регион.

Налог добавляется сверх тарифа Blue Express: цены Blue Express включают IVA. Установите Tax status в None (no tax on shipping).

Карта не открывается: карта загружается с widget-pudo.blue.cl в браузере покупателя, поэтому этот адрес должен быть доступен и не блокироваться на вашем сайте.

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

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

Удаление

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

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