VibeFox Envioclick for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Учётная запись Envioclick (только для тарифов в реальном времени): учётная запись Envioclick в Мексике или Колумбии с доступом к API. Ключ API находится в вашей учётной записи Envioclick: Mi cuenta (вверху справа) > Información del API. Если вы используете только фиксированные цены, учётная запись Envioclick не нужна.

User-Agent (только Мексика): Envioclick Mexico требует значение User-Agent для каждого запроса к API. Запросите его в службе поддержки Envioclick (soporte.tecnico@envioclick.com).

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

Установка

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

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Envioclick в списке модулей и нажмите Configure.

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

4. Введите ключ API, выберите страну API, укажите User-Agent (Мексика), почтовый индекс или код DANE отправления и адрес отправления. Если валюта магазина по умолчанию не MXN и не COP, введите курс конвертации валюты. Для Колумбии нажмите Add Colombian departments, если страница это предлагает.

5. При необходимости добавьте фиксированные цены по странам и запасную стоимость, затем нажмите Save.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Envioclick > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш тарифов Envioclick. Числовые поля принимают и точку, и запятую как десятичный разделитель.

Если задан ключ API, в верхней части страницы появляются предупреждения, если тарифы в реальном времени не могут работать: нет курса конвертации для валюты магазина, отличной от MXN или COP, нет User-Agent для Мексики, нет почтового индекса или кода DANE отправления, либо нет адреса отправления для Колумбии. Страница также предупреждает, если единица веса или размеров вашего магазина не распознана; задайте kg, g, lb или oz и cm, mm, m или in в International > Localization (Local units). При сохранении модуль проверяет, что Method title — корректное название перевозчика, что числовые поля содержат неотрицательные числа, что Currency conversion rate больше 0, что Minimum weight не больше Maximum weight и что код отправления содержит 5 цифр для Мексики или 8 цифр (либо 5-значный код муниципалитета) для Колумбии. Если проверка не пройдена, показывается ошибка и ничего не сохраняется.

Общие

Зоны, группы клиентов и ограничения по размеру перевозчика задаются в Shipping > Carriers (или используйте Ignore shipping zones ниже). Настройки этой страницы применяются ко всем зонам.

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

Method title: название перевозчика, которое покупатель видит в корзине и при оформлении заказа. По умолчанию: Envioclick Shipping. Обязательно.

Carrier in the title: показывает перевозчика Envioclick и ожидаемый срок доставки тарифа в реальном времени под перевозчиком при оформлении заказа, например «Estafeta Express, 1 day». Перевозчик в любом случае сохраняется в заказе и показывается на страницах заказа. По умолчанию: включено.

API Envioclick (тарифы в реальном времени)

Необязательно. Без ключа API используются только фиксированные цены. В разделе есть ссылки на документацию API Envioclick для Мексики и Колумбии. Тарифы в реальном времени запрашиваются только для направлений внутри страны API. Доставка в другие страны использует фиксированные цены.

API key: ваш ключ API Envioclick из Mi cuenta > Información del API. Он передаётся в заголовке «Authorization». После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

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

API country: страна вашей учётной записи Envioclick.

Colombian departments: только для Колумбии. В PrestaShop по умолчанию нет колумбийских департаментов. Без них распознаются только названия городов, уникальные в Колумбии; департамент позволяет различать муниципалитеты с одинаковыми названиями. Кнопка Add Colombian departments добавляет 33 департамента как регионы Колумбии (ISO-коды ANT, DC и т. д.), включает «Contains states» для Колумбии и добавляет поле департамента в колумбийскую форму адреса. Уже существующие департаменты повторно не добавляются. Когда всё готово, поле показывает, сколько департаментов есть у колумбийских адресов.

User-Agent (Мексика): значение, выданное службой поддержки Envioclick (soporte.tecnico@envioclick.com), например EcUserAgent-2/123456. Обязательно для Мексики; без него тарифы в реальном времени для Мексики не запрашиваются. Для Колумбии необязательно.

Выбор перевозчика: Cheapest (по умолчанию) или Fastest (then cheapest). Envioclick возвращает тарифы от нескольких перевозчиков, а покупатель получает один тариф.

Тарифы на получение в пункте выдачи: также учитывать тарифы «Ocurre», при которых покупатель забирает посылку в пункте выдачи перевозчика. Если выключено, используются только тарифы доставки на дом. Услуги наложенного платежа (COD) никогда не используются. По умолчанию: выключено.

Курс конвертации валюты: Envioclick считает в MXN (Мексика) или COP (Колумбия). Если валюта магазина по умолчанию другая, введите стоимость 1 MXN или 1 COP в валюте вашего магазина, например 0.05. Объявленная стоимость посылки пересчитывается так же. Оставьте поле пустым, если валюта магазина — MXN или COP. Без курса тарифы в реальном времени в другой валюте не используются.

Отправление из

Используется для тарифов в реальном времени. Пустые поля берутся из адреса магазина в Shop Parameters > Contact > Stores, если магазин находится в стране API.

Origin postcode / DANE code: Мексика: 5-значный почтовый индекс. Колумбия: 8-значный код DANE муниципалитета, например 11001000 для Боготы; 5-значный код муниципалитета (11001) тоже работает.

Origin address: улица и номер адреса забора отправлений. Обязательно для Колумбии, необязательно для Мексики.

Фиксированные цены

Используются, когда тарифа в реальном времени нет: нет ключа API, направление за пределами страны API, ошибка API или нет перевозчика для маршрута.

Price per country: таблица из 2-буквенных кодов стран и цен в валюте магазина по умолчанию, без налогов. Нажмите Add row, чтобы добавить страну, и значок корзины, чтобы удалить её. Используйте * как код страны для всех стран без собственной строки.

Fallback cost: используется, когда тарифа в реальном времени нет и ни одна строка таблицы не подходит. Оставьте поле пустым, чтобы в этом случае скрывать перевозчика.

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

Условия

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

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

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

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

Tax: налоговое правило перевозчика или No tax. Тарифы Envioclick уже включают налоги перевозчиков, поэтому выберите No tax, чтобы не начислять налог на доставку дважды.

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

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

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

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

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

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

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

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

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

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

Если задан ключ API и направление находится в стране API, модуль запрашивает у Envioclick тарифы. В Мексике запрос отправляется, когда покупатель ввёл 5-значный почтовый индекс. В Колумбии он отправляется, когда распознаны департамент и муниципалитет (акценты и регистр не имеют значения). Модуль выбирает самый дешёвый или самый быстрый тариф, который не является наложенным платежом, и пересчитывает его в валюту магазина по умолчанию. Затем цена показывается в валюте корзины покупателя.

Посылка всегда одна коробка: общий вес в кг, длина и ширина самого большого товара и высота, при которой сохраняется общий объём всех товаров. Товары без размеров считаются как 10 × 10 × 10 см. Корзина без веса отправляется как 0,5 кг. Объявленная стоимость — это промежуточный итог корзины.

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

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

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

Заказы

Когда заказ оформляется с перевозчиком Envioclick, тариф, рассчитанный для его корзины, сохраняется вместе с заказом и больше не меняется. На странице заказа в панели администрирования показывается блок Envioclick shipping с Envioclick carrier, Estimated delivery и Envioclick rate ID (для тарифа в реальном времени), Price source (Envioclick live rate, Fixed price per country, Fallback cost или Free shipping threshold) и Calculated price (excl. tax). Для тарифа в реальном времени на странице заказа покупателя показывается Shipping carrier. Накладную создайте в своей учётной записи Envioclick.

У заказов с фиксированной ценой нет перевозчика Envioclick.

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

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

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

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

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

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

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

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

Тарифы в реальном времени не появляются: прочитайте предупреждения вверху страницы модуля, затем включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице модуля. Частые причины: нет курса конвертации (валюта магазина не MXN и не COP), нет User-Agent (Мексика), нет почтового индекса или кода DANE отправления, почтовый индекс покупателя (Мексика) или город (Колумбия) ещё не введён, направление за пределами страны API или нет перевозчика для маршрута.

Зачем нужен курс конвертации? Envioclick возвращает цены только в мексиканских или колумбийских песо. Модуль никогда не показывает сумму в песо как сумму в другой валюте.

Колумбия: город не распознаётся: нажмите Add Colombian departments на странице модуля, чтобы покупатели могли выбрать департамент, и проверьте, правильно ли написано название муниципалитета. 8-значный код DANE, введённый как почтовый индекс, тоже работает.

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

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

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

Удаление

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

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